Merge pull request #156 from mathworks/src_folder_doc

document source folder support

Author: mw-hrastega

CONFIGDOC.md

@@ -1,4 +1,4 @@
-When you define a [Jenkins™ Pipeline](https://www.jenkins.io/doc/book/pipeline/), whether in the web UI or with a [`Jenkinsfile`](https://www.jenkins.io/doc/book/pipeline/jenkinsfile/), you can use the plugin to run your MATLAB® code or Simulink® models on Jenkins. This guide demonstrates how to configure the plugin and use it in freestyle, multi-configuration, and Pipeline projects.
+When you define an automated pipeline of tasks in Jenkins™, whether in the web UI or with a [`Jenkinsfile`](https://www.jenkins.io/doc/book/pipeline/jenkinsfile/), you can use the plugin to run your MATLAB® code or Simulink® models. This guide demonstrates how to configure the plugin and use it in freestyle, multi-configuration, and Pipeline projects.
 
 
 -  [Configure Plugin in Web UI](#configure-plugin-in-web-ui)
@@ -10,8 +10,8 @@ When you define a [Jenkins™ Pipeline](https://www.jenkins.io/doc/book/pipe
 -  [Set Up Multi-Configuration Project](#set-up-multi-configuration-project)
 -  [Set Up Pipeline Project](#set-up-pipeline-project)
    -  [Add MATLAB to System Path](#add-matlab-to-system-path)
-   -  [Use `runMATLABCommand` Step](#use-runmatlabcommand-step)
-   -  [Use `runMATLABTests` Step](#use-runmatlabtests-step) 
+   -  [Use the runMATLABCommand Step](#use-the-runmatlabcommand-step)
+   -  [Use the runMATLABTests Step](#use-the-runmatlabtests-step) 
    -  [Use MATLAB in Matrix Build](#use-matlab-in-matrix-build)
 
 ## Configure Plugin in Web UI
@@ -20,7 +20,8 @@ You can use the web UI provided by Jenkins to configure the plugin in freestyle
 ### Use MATLAB in Build
 Once you install the plugin, **Use MATLAB version** appears in the **Build Environment** section of the project configuration window.
 
-![matlab_path](https://user-images.githubusercontent.com/48831250/76883191-1c528b00-6852-11ea-9242-7d143f8a5c46.png)
+
+![matlab_path](https://user-images.githubusercontent.com/48831250/94472251-75ec2880-0198-11eb-8d95-7a67c802cae8.png)
 
 Select **Use MATLAB version** to specify the full path to the MATLAB root folder that should be used for the build. The information in the **MATLAB root** box enables the plugin to prepend MATLAB to the system PATH environment variable of the build agent. 
 
@@ -30,9 +31,9 @@ If the build agent already has your desired MATLAB on the path, then you are not
 
 | Platform     | Path to MATLAB Root Folder      |
 |--------------|---------------------------------|
-| Windows® | C:\Program Files\MATLAB\R2020a  |
-| Linux®   | /usr/local/MATLAB/R2020a        |
-| macOS          | /Applications/MATLAB_R2020a.app |
+| Windows® | C:\Program Files\MATLAB\R2020b  |
+| Linux®   | /usr/local/MATLAB/R2020b        |
+| macOS          | /Applications/MATLAB_R2020b.app |
 
 ### Specify Build Steps
 When you set up the **Build** section of the project configuration window, the plugin provides you with the **Run MATLAB Command** and **Run MATLAB Tests** build steps.
@@ -44,21 +45,21 @@ The **Run MATLAB Command** build step enables you to specify MATLAB commands tai
 
 If you specify more than one MATLAB command, use a comma or semicolon to separate the commands. The build fails if the execution of any command results in an error.
 
-![run-matlab-command](https://user-images.githubusercontent.com/48831250/79279466-1d400200-7e7c-11ea-9ef5-0d006f100eea.png)
+![run_matlab_command](https://user-images.githubusercontent.com/48831250/94472499-d8ddbf80-0198-11eb-8f25-ead3c4039f55.png)
+
 
 If you need to specify several MATLAB commands, consider writing a MATLAB script or function as part of your repository and executing this script or function instead. 
 
 Test artifacts are not autogenerated if you choose to run tests using this build step. You can generate your desired test artifacts by configuring the test runner in the script or function that you invoke from the **Command** box.
 
 #### Run MATLAB Tests
-This build step uses a default setting to run tests authored using the MATLAB Unit Testing Framework or Simulink Test™. If your source code is organized into files and folders within a MATLAB project, then the plugin includes any test files in the project that have been labeled as `Test`. If your code does not leverage a MATLAB project or uses a MATLAB release before R2019a, then the plugin includes all tests in the project workspace, including its subfolders. 
+This build step uses a default setting to run tests authored using the MATLAB Unit Testing Framework or Simulink Test™. If your source code is organized into files and folders within a MATLAB project, then the plugin includes any test files in the project that have been labeled as `Test`. If your code does not leverage a MATLAB project or uses a MATLAB release before R2019a, then the plugin includes all tests in the project workspace, including its subfolders.
 
-The **Run MATLAB Tests** build step enables you to generate different types of test artifacts. To publish the test results, you can use these artifacts with other Jenkins plugins. By default, the plugin assigns a name to each selected artifact and stores it in the `matlabTestArtifacts` folder of the project workspace. You can override the default artifact name and location by specifying a path relative to the project folder in the **File path** box. (If you leave the text box empty, the plugin does not generate an artifact.)  
- 
-![run_matlab_tests](https://user-images.githubusercontent.com/48831250/84545463-54406180-accd-11ea-890e-7a6bb9ee051b.png)
+With the **Run MATLAB Tests** build step, you can optionally specify the location of folders containing source code, relative to the project root folder. When you specify a folder in the **Folder path** box, the plugin adds the specified folder and its subfolders to the top of the MATLAB search path. You can specify more folders by clicking **Add Folder**. If you specify folders, MATLAB uses only the source code in the specified folders and their subfolders to generate a coverage report. 
 
+ ![run_matlab_tests](https://user-images.githubusercontent.com/48831250/94472880-64efe700-0199-11eb-8c2f-e733f104ba95.png)
 
-If you do not select any of the test artifact check boxes, the tests still run, and test failures fail the build.
+The **Run MATLAB Tests** build step enables you to generate different types of test artifacts. To publish the test results, you can use these artifacts with other Jenkins plugins. By default, the plugin assigns a name to each selected artifact and stores it in the `matlabTestArtifacts` folder of the project workspace. You can override the default artifact name and location by specifying a path relative to the project folder in the **File path** box. If you leave the text box empty, the plugin does not generate an artifact. If you do not select any of the test artifact check boxes, the tests still run, and test failures fail the build.  
 
 The **Run MATLAB Tests** build step produces a MATLAB script file and uses it to run the tests and generate the test artifacts. The plugin writes the contents of this file to the build log. You can review the build log in **Console Output** to understand the testing workflow.
 
@@ -72,10 +73,11 @@ To configure the plugin for a freestyle project, specify the location where MATL
 
 1) In the **Build Environment** section of the project configuration window, select **Use MATLAB version**. Then, enter the full path to the MATLAB root folder in the **MATLAB root** box. (You can skip this step if MATLAB has already been added to the path on the build agent.)
 
-![build_environment](https://user-images.githubusercontent.com/48831250/76798534-23bc5a80-67a6-11ea-9a48-861cbbc7b0ba.png)
+![build_environment](https://user-images.githubusercontent.com/48831250/94472063-31f92380-0198-11eb-90c1-adb48e7f5f2b.png)
+
 
 2) Add the required build steps in the **Build** section:
-   *   If you add the [**Run MATLAB Tests**](#run-matlab-tests) build step, select check boxes for the artifacts to be generated in the project workspace.
+   *   If you add the [**Run MATLAB Tests**](#run-matlab-tests) build step, specify the source code and the artifacts to be generated in the project workspace.
    *   If you add the [**Run MATLAB Command**](#run-matlab-command) build step, enter your commands in the **Command** box. 
 
 ## Set Up Multi-Configuration Project
@@ -87,21 +89,25 @@ To configure the plugin for a multi-configuration project, specify the locations
 
 1) Add a user-defined axis in the **Configuration Matrix** section to represent the MATLAB versions in the build. Specify the name of the axis in the **Name** box and its values in the **Values** box. Separate the values with a space. In this example, four MATLAB versions are specified to run the same set of tests.
 
-![axis_version](https://user-images.githubusercontent.com/48831250/76800706-9a5b5700-67aa-11ea-98f0-25f2b7f3658c.png)
+![axis_version](https://user-images.githubusercontent.com/48831250/94473728-96b57d80-019a-11eb-8e53-7e8960430e9b.png)
+
 
 You can define several axes in the **Configuration Matrix** section. For example, add the TEST_TAG axis specifying the possible test tags for a group of tests.
 
-![axis_version_testtag](https://user-images.githubusercontent.com/48831250/76800736-aa733680-67aa-11ea-86a7-a984d5795e11.png)
+![axis_version_testtag](https://user-images.githubusercontent.com/48831250/94474181-4559be00-019b-11eb-9e22-6771f353505b.png)
+
 
 2) In the **Build Environment** section, select **Use MATLAB version** and then specify the locations where MATLAB is installed using the user-defined axis name. In this example, **$VERSION** in the **MATLAB root** box is replaced by one axis value per build iteration. 
 
-![build_environment_matrix](https://user-images.githubusercontent.com/48831250/76800665-87488700-67aa-11ea-9dbd-3c3ab518afa7.png)
+![build_environment_matrix](https://user-images.githubusercontent.com/48831250/94474620-e779a600-019b-11eb-8b6a-7e308484c591.png)
+
 
 3) Add the required build steps in the **Build** section:
-   *   If you add the [**Run MATLAB Tests**](#run-matlab-tests) build step, select check boxes for the artifacts to be generated in the project workspace.
+   *   If you add the [**Run MATLAB Tests**](#run-matlab-tests) build step, specify the source code and the artifacts to be generated in the project workspace.
    *   If you add the [**Run MATLAB Command**](#run-matlab-command) build step, enter your commands in the **Command** box. You can use the user-defined axes to create your commands. For example:
 
-![run_matlab_command_matrix](https://user-images.githubusercontent.com/48831250/76883848-21fca080-6853-11ea-8ad3-89f85b997608.png)
+![run_matlab_command_matrix](https://user-images.githubusercontent.com/48831250/94475242-c9607580-019c-11eb-9ee5-8a0d2f95f5bf.png)
+
 
 **Note:**
 * Both **$VAR** and **${VAR}** are valid formats for accessing the values of the user-defined axis **VAR**. On macOS platforms, the **${VAR}** format is recommended.
@@ -122,16 +128,16 @@ You also can define your Pipeline directly in the project configuration window.
 ### Add MATLAB to System Path
 When Jenkins executes MATLAB-related steps in your Pipeline, it uses the first MATLAB version on the system path. If the PATH environment variable of the build agent does not include any MATLAB versions, you must update the variable with the MATLAB root folder that should be used for the build.
 
-To update the system PATH environment variable using Declarative Pipeline syntax, use an `environment` block in your `Jenkinsfile`. For example, prepend MATLAB R2020a to the system PATH environment variable and use it to run your command.
+To update the system PATH environment variable using Declarative Pipeline syntax, use an `environment` block in your `Jenkinsfile`. For example, prepend MATLAB R2020b to the system PATH environment variable and use it to run your command.
 
 ```groovy
 // Declarative Pipeline
 pipeline {
    agent any
    environment {
-       PATH = "C:\\Program Files\\MATLAB\\R2020a\\bin;${PATH}"   // Windows agent
-    // PATH = "/usr/local/MATLAB/R2020a/bin:${PATH}"   // Linux agent
-    // PATH = "/Applications/MATLAB_R2020a.app/bin:${PATH}"   // macOS agent    
+       PATH = "C:\\Program Files\\MATLAB\\R2020b\\bin;${PATH}"   // Windows agent
+    // PATH = "/usr/local/MATLAB/R2020b/bin:${PATH}"   // Linux agent
+    // PATH = "/Applications/MATLAB_R2020b.app/bin:${PATH}"   // macOS agent    
    }
     stages{
         stage('Run MATLAB Command') {
@@ -148,14 +154,14 @@ If you define your Pipeline using Scripted Pipeline syntax, set the PATH environ
 ```groovy
 // Scripted Pipeline
 node {
-        env.PATH = "C:\\Program Files\\MATLAB\\R2020a\\bin;${env.PATH}"   //Windows agent
-     // env.PATH = "/usr/local/MATLAB/R2020a/bin:${env.PATH}"   //Linux agent
-     // env.PATH = "/Applications/MATLAB_R2020a.app/bin:${env.PATH}"   //macOS agent
+        env.PATH = "C:\\Program Files\\MATLAB\\R2020b\\bin;${env.PATH}"   //Windows agent
+     // env.PATH = "/usr/local/MATLAB/R2020b/bin:${env.PATH}"   //Linux agent
+     // env.PATH = "/Applications/MATLAB_R2020b.app/bin:${env.PATH}"   //macOS agent
         runMATLABCommand "disp('Hello World!')"
 }
 ``` 
 
-### Use `runMATLABCommand` Step
+### Use the runMATLABCommand Step
 Use the `runMATLABCommand` step in your Pipeline to run MATLAB scripts, functions, and statements tailored to your specific needs. You can use this task to flexibly customize your test run or run any MATLAB commands.
 
 You must provide `runMATLABCommand` with a string that specifies the command you want to execute. If the command is the name of a MATLAB script or function, do not specify the file extension. If you specify more than one MATLAB command, use a comma or semicolon to separate the commands.
@@ -194,7 +200,7 @@ MATLAB exits with exit code 0 if the specified script, function, or statement ex
 
 When you use the `runMATLABCommand` step, all of the required files must be on the MATLAB search path.
 
-### Use `runMATLABTests` Step
+### Use the runMATLABTests Step
 
 Use the `runMATLABTests` step in your Pipeline to run all tests in your MATLAB project and generate artifacts. MATLAB includes any files in your project that have a `Test` label. If your Pipeline does not leverage a MATLAB project or uses a MATLAB release before R2019a, then MATLAB includes all tests in the the root of your repository, including its subfolders.
 
@@ -227,7 +233,7 @@ node {
 
  To generate artifacts using the `runMATLABTests` step, provide the step with one or more name-value pair arguments to specify the artifacts and the locations to save them. Use a colon to separate names and values.
 
- For example, define a Declarative Pipeline to run the tests in your MATLAB project, and then generate a JUnit test results report and a Cobertura code coverage report at specified locations on the build agent.
+ For example, define a Declarative Pipeline to run the tests in your MATLAB project, and then generate a JUnit test results report and a Cobertura code coverage report at specified locations on the build agent. Generate the coverage report for only the code in the `source` folder located in the root of your repository. 
 
 
 ```groovy
@@ -239,7 +245,8 @@ pipeline {
             steps
             {
                 runMATLABTests(testResultsJUnit: 'test-results/results.xml',
-                               codeCoverageCobertura: 'code-coverage/coverage.xml')
+                               codeCoverageCobertura: 'code-coverage/coverage.xml',
+                               sourceFolder: ['source'])
             }       
         }                
     } 
@@ -252,7 +259,8 @@ Define a Scripted Pipeline to run your tests and generate artifacts.
 // Scripted Pipeline
 node {
     runMATLABTests(testResultsJUnit: 'test-results/results.xml',
-                   codeCoverageCobertura: 'code-coverage/coverage.xml') 
+                   codeCoverageCobertura: 'code-coverage/coverage.xml',
+                   sourceFolder: ['source']) 
 }
 ``` 
 
@@ -268,12 +276,13 @@ node {
 | testResultsSimulinkTest 	| Path to export Simulink Test Manager results in MLDATX format (requires Simulink Test license and is supported in MATLAB R2019a or later).<br/>**Example:** `'test-results/results.mldatx'` 	|
 | codeCoverageCobertura   	| Path to write code coverage report in Cobertura XML format.<br/>**Example:** `'code-coverage/coverage.xml'`     	|
 | modelCoverageCobertura  	| Path to write model coverage report in Cobertura XML format (requires Simulink Coverage™ license and is supported in MATLAB R2018b or later).<br/>**Example:** `'model-coverage/coverage.xml'`   	|
+| sourceFolder  	| Locations of the folders containing source code, relative to the project root folder. The specified folders and their subfolders are added to the top of the MATLAB search path. To generate a coverage report, MATLAB uses only the source code in the specified folders and their subfolders. <br/>**Example:** `['source']`<br/>**Example:** `['src/folderA', 'src/folderB']`   	|
 
 
 ## Use MATLAB in Matrix Build
 Similar to multi-configuration projects, you can use MATLAB as part of a [matrix](https://www.jenkins.io/doc/book/pipeline/syntax/#declarative-matrix) build in Pipeline projects. For example, you can define a Pipeline to run your test suite on different platforms or against different versions of MATLAB.
 
-This example shows how to define a Declarative Pipeline to run your MATLAB code and generate test artifacts using MATLAB R2018b, R2019a, and R2020a. The Pipeline has a `matrix` section to define the possible name-value combinations that should run in parallel. 
+This example shows how to define a Declarative Pipeline to run your MATLAB code and generate test artifacts using MATLAB R2018b, R2019a, and R2020b. The Pipeline has a `matrix` section to define the possible name-value combinations that should run in parallel. 
 
 ```groovy
 // Declarative Pipeline
@@ -289,7 +298,7 @@ pipeline {
                 axes {
                     axis {
                         name 'MATLAB_VERSION'
-                        values 'R2018b', 'R2019a', 'R2020a'
+                        values 'R2018b', 'R2019a', 'R2020b'
                     }
                 }
                 stages {