Update docs for wording. Add information about customSDK folder and help text testing

Add-command.md

@@ -14,16 +14,14 @@ or `cluster`. The command group should correspond to the REST API target
 entity.
 
 Write a new python function in the file that corresponds to the command
-group. The files that contain custom functions are in
+group. The files with custom functions are in
 `src/stctl/custom_<group>.py`.
 
 For more information, see the page on [[custom commands|Custom-commands]].
 
 ### Find standard command
 
-Identify what is the name of the python function in the Service Fabric Python
-SDK by inspecting the `azure-servicefabric` package. There is a class that
-contains a number of functions that correspond to the REST APIs.
+Look in the `azure-servicefabric` package for what standard commands exist. Every service fabric REST API will have a corresponding function of the same name.
 
 For more information, see the page on [[standard commands|Standard-commands]].
 
@@ -61,5 +59,10 @@ For any custom commands, add unit tests to the appropriate command group
 file in `src/sfctl/tests`. Test the logic inside your custom python function
 that you previously wrote.
 
-For standard commands where no custom python function was necessary, add
-a scenario test in `scenario_test.py` that invokes your command at least once.
+For all commands, add a paths generation test in `paths_generation_test.py`.
+
+For all commands, add a help text verification test in `help_text_test.py`.
+
+For custom commands, consider adding a scenario test in `scenario_test.py` that calls your command at least once. 
+
+For more information about testing, see [[testing|Testing]].

Checklist.md

@@ -1,16 +1,17 @@
-This checklist comprises of things to check before submitting a pull request:
+This checklist lists items to check before submitting a pull request:
 
 ## Documentation
 
 - Ensure that the PR has a descriptive summary.
 - Update the `<root>\CODEOWNERS` file as appropriate. Instruction for how to add is included in the file itself.
 - Update the `<root>\src\README.rst` file to summarize the changes included in the pull request. If required by semantic versioning, include change logs under a new version. Include the PR number at the end of each entry, with format `New feature (#70)` where 70 is the pull request number.
-- In the `<root>\src\README.rst` file, all new entries which are not published yet should be marked as 'Unreleased'.
+- In the `<root>\src\README.rst` file, all new entries that are not published yet should be marked as 'Unreleased'.
 - For each new command added, make sure appropriate documentation is added to the corresponding help file.
+- If your command has a custom help text section, check that the content is still current.
 
 ## Testing
-- Any new functionality should include testing. Tests which require a live cluster connection are optional, and should be avoided if possible. Non live testing is required. Suggested testing includes unit testing, as well as paths generation test, which can be found in `<root>\src\sfctl\tests\request_generation_test.py`.
-- Any new commands, command groups, or commands whose names have been changed should include a test in the `<root>\src\sfctl\tests\request_generation_test.py` to ensure that the help text is being displayed.
+- Any new functionality should include testing. Tests that require a live cluster connection are optional, and should be avoided if possible. Non live testing is required. Suggested testing includes unit testing, as well as paths generation test, which can be found in `<root>\src\sfctl\tests\request_generation_test.py`.
+- Any new commands, command groups, or commands whose names have been changed, should include a test in the file `<root>\src\sfctl\tests\help_text_test.py`. This test helps ensure that the help text is present and displayed correctly.
 - Make sure that all test assert calls include an explanatory message for ease of debugging errors.
 
 ## Conventions

Client-logic.md

@@ -1,4 +1,6 @@
-The Service Fabric Python SDK requires a client to be created prior to invoking
+The Service Fabric CLI acts as a wrapper around the Service Fabric Python SDK, which is auto generated from the Service Fabric REST/Swagger specs.
+
+The Python SDK requires a client to be created before calling
 any REST APIs. The client generation logic has been modified to support
 both AAD and client certificate authentication.
 
@@ -8,8 +10,7 @@ The client generation function is specified in `src/sfctl/apiclient.py`.
 Here, the function `create` will create a client using the Service Fabric
 Python SDK.
 
-Settings for the client such as the cluster endpoint and authentication options
-are persisted to disk in a temporary file in the users home directory.
+Settings for the client are persisted to disk in a temporary file in the user's home directory. Settings can include choices such as the cluster endpoint and authentication options.
 
 ## Knack config documentation
 
@@ -18,5 +19,5 @@ For more information about how these settings are persisted, see the
 
 ## Calling client functions
 
-The generated client can be used to then invoke any REST API. The APIs are
+The generated client can be used to then call any REST API. The APIs are
 all functions of the generated client.

Command-help.md

@@ -33,12 +33,12 @@ property, see the following sections:
 
 ### Summaries
 
-Commands, command groups, and parameters can all contain `short-summary`
+Commands, command groups, and parameters can all have `short-summary`
 properties. Parameter short summaries are displayed alongside parameters when
 requesting command help. Command short summaries are displayed when request
 command group help.
 
-Furthermore, commands can contain a `long-summary` property that is shown
+Furthermore, commands can have a `long-summary` property that is shown
 when help is requested for the specific command. A long summary is a more
 detailed description.
 

Command-params.md

@@ -1,17 +1,19 @@
 By default all commands pass arguments as strings. That means the mapped
 Python functions are called with string arguments. To parse objects or
-convert the string arguments to other type, add CLI arguments to the associated
+convert the string arguments to another type, add CLI arguments to the associated
 commands.
 
-Any type conversion is performed to modify the command-line arguments
+Type conversion is performed to modify the command-line arguments
 into different Python types.
 
-## Argument scope
+Arguments are added by default from the referenced python definition as string type. You only need to add to `src/sfctl/params.py` when the parameter has a non-string type.
 
-All arguments are specified in the `src/sfctl/params.py` file. Each argument
+## Arguments
+
+All arguments that require a type conversion are specified in the `src/sfctl/params.py` file. Each argument
 is specified inside an argument context.
 
-For example, the timeout argument, or `-t` is defined with a global context:
+For example, the `--timeout` argument, or `-t`, is defined with a global context:
 
 ```python
 with ArgumentsContext(self, '') as arg_context:
@@ -20,8 +22,7 @@ with ArgumentsContext(self, '') as arg_context:
                          help='Server timeout in seconds')
 ```
 
-Here, the second argument to the `ArgumentsContext` is the command that has an
-argument associated with it.
+`timeout` has global context because the second argument to the `ArgumentsContext` is an empty string. The second argument specifies the scope. It is the command that has an argument associated with it. For example, if the value is `application create`, then the argument conversions will apply only to the create command in application, and not any other command, since it uses the smallest scope.
 
 ## Complex types
 
@@ -30,23 +31,23 @@ Take a look at how `service create` specifies int arguments.
 ```python
 with ArgumentsContext(self, 'service create') as arg_context:
     arg_context.argument('instance_count', type=int)
+    arg_context.argument('load_metrics', type=json_encoded)
 ```
 
 This code associates an argument specified by `--instance-count` with the
 command `sfctl service create`. Furthermore, it calls the function `int` on
-the string input prior to invoking the mapped Python command.
+the string input prior to invoking the mapped Python command. The `--load-metrics` argument will be json decoded in the above example.
 
 ### Custom types
 
-The argument to `type` can be any function that takes a string as the single
-argument, and then returns the parsed object. This optional argument is useful
-if you want to perform additional modification to an argument prior to invoking
+The `type` argument for `arg_context.argument` can be any function that takes a string as input. It should return the parsed object. This optional argument can be used
+if you want to perform additional modification to an argument before invoking
 the mapped python function.
 
 ## Optional arguments
 
-Optional arguments can be specified in one of two ways. They can be either a
-custom argument, or as an optional argument in the Python function definition.
+Optional arguments can be specified in one of two ways. They can either be a
+custom argument, or an optional argument in the Python function definition.
 
 If specifying an optional custom argument, specify the optional `default`
 argument when calling `argument` from the `ArgumentsContext`.

Contributing.md

@@ -1,31 +1,30 @@
-When contributing to this repository abide by the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
-We try to follow the same conventions of forking and merging pull requests as many other GitHub public repositories.
+When contributing to this repository, abide by the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+Additionally, follow the same conventions of forking and merging pull requests as many other GitHub public repositories.
 Follow these steps to properly contribute code changes
 
 ## Fork
 
-From the GitHub repository home page, select **Fork**, this will create a copy
+From the GitHub repository home page, select **Fork**. Forking will create a copy
 of the repository under your own account. Clone this repository.
 
 ## Making changes
 
-Be sure you are familiar with standard git work-flows, such as editing, committing
-and pushing prior to attempting to make changes.
+Be sure that you are familiar with standard git work-flows. These include editing, committing, and pushing, prior to attempting to make changes.
 
 To set up your development environment, follow the [developer setup](Developer-setup.md) documentation.
 
-When making changes we suggest the following practices:
+When making changes, the following practices are recommended:
 
 - Commit with meaningful messages, it will help reviewers understand your work
 - Start with a recent commit from the `master` branch, changes based on stale commits will be rejected
 - Ensure that all new features include automated testing
 
-Be sure to also follow our [coding conventions](Conventions.md).
+Be sure to also follow the [coding conventions](Conventions.md).
 
 ## Submitting work
 
 Once you have validated your changes and feel confident you are ready to contribute back your work, submit a pull request.
 
-All pull requests should target the `master` branch, as this is the main development branch.
+All pull requests should target the `master` branch, as it is the main development branch.
 
-From here follow the guidance of reviewers to get your work merged.
+From here, follow the guidance of reviewers to get your work merged.

Conventions.md

@@ -18,7 +18,8 @@ A correct example:
 # pylint: disable=too-few-public-methods
 ```
 
-If you don't know the human readable value, you can run the following in command line, which returns a list of error codes, their human readable formats, and their error messages.
+If you don't know the human readable value, you can run the following command in your virtual environment, which returns a list of error codes, their human readable formats, and their error messages.
+
 ```
 pylint --list-msgs
 ```

Custom-commands.md

@@ -1,7 +1,8 @@
-Custom commands are one type of Service Fabric command. Custom commands tend
-to require more operations, such as file I/O or HTTP request modification. For
-example, the `application upload` command is a good example of a custom
-command since it sends multiple requests and performs client file I/O.
+Custom commands are one type of Service Fabric command in the CLI. They are usually commands that are either not defined in the Service Fabric Python SDK, or are commands that require a wrapper around or modifications to the SDK.
+
+The most common reasons for requiring a custom command are that the operation requires file I/O, HTTP request modification, or simplification of standard command parameters. For
+example, the `application upload` command is a custom
+command. It sends multiple requests and performs client file I/O. 
 
 For more information about the differences between custom and standard
 commands, see the [[related documentation|Command-mapping]].

Internal-development.md

@@ -1,25 +1,31 @@
-This page is for Service Fabric internal developers who are adding commands
-which take dependency on a not yet released version of the python SDK.
+This page is for Service Fabric internal developers who are adding commands that take dependency on a not yet released version of the python SDK.
 
 ## Setting Target to Unreleased Python SDK
 
+### Setting target on local machine
+
 The easiest way to set up for internal development work is to complete the regular
-[setup steps](Developer-setup.md). After following those steps, simply swap out
+[setup steps](Developer-setup.md). After following those steps, swap out
 the downloaded Python SDK with one containing the changes you want to test against.
 To swap:
 
 1. Build the version of Swagger containing the changes you want.
 2. Copy the Python SDK generated into the environment folder of your virtual environment.
 
-The generated Python SDK from Swagger can be found in the out folder. It should be at 
+The generated Python SDK from Swagger can be found in the `out` folder. It should be at 
 `out\debug-AMD64\swagger-sfclient\<swagger-version>\python_sdk\azure\servicefabric`.
-Copy everything inside that folder into the site packages of your virtual environment, which 
-should be located at path (from root): 
+Copy everything inside the swagger `out\debug-AMD64...\servicefabric` folder into the site packages of your virtual environment. The site packages should be located at path (from root): 
 `<your-environment>\Lib\site-packages\azure\servicefabric`. You can delete all items in
 the `servicefabric` folder, including the cache folder, prior to pasting your SDK.
 
-After swapping, you can follow the steps to add a new command as normal.
+After swapping, you can follow the instructions add a new command as normal.
+
+### Setting target for Travis CI
+
+If this step is needed for development, it means that the Travis CI checks will fail using the public python SDK. To get around this issue, copy the SDK from the swagger out folder into `<root>/customSDK`. The path should contain `<root>/customSDK/servicefabric/service_fabric_client_ap_is.py`.
+
+Travis CI will pick up this uploaded custom SDK if there is an 'Unreleased' section in the README file.
 
 ## Documenting
 
-All public facing documentation should be placed in the help files, and not as part of docstrings in the function.
+All public facing documentation should be placed in the help files rather than as function docstring. Avoid copying the help documents directly from `service_fabric_client_ap_is.py`. 

Overview.md

@@ -1,4 +1,3 @@
-The Service Fabric CLI is a command line interface which provides cluster 
+The Service Fabric CLI is a command-line interface that provides cluster 
 management functionality. It is written in Python, and acts as a wrapper
-to a Python SDK which is generated by AutoRest using the Service Fabric
-Swagger specifications.  
+to a Python SDK. The Python SDK is generated by AutoRest using the Service Fabric Swagger specifications.  

Standard-commands.md

@@ -31,8 +31,7 @@ that gets mapped to the CLI syntax `sfctl cluster health`.
 
 ## Test
 
-Once the command has a mapping, be sure to include Nose test cases for the
-command logic. The tests should be added as functions that include the
-phrase `test` at the end of the function name.
+Once the command has a mapping in `commands.py`, be sure to include tests for the command. If adding new tests, the tests should be added as functions that include the
+phrase `test` at the start of the function name.
 
 All of the unit tests are under the `src/sfctl/tests` folder.

Testing.md

@@ -1,9 +1,8 @@
 Four different categories of tests are used: unit tests, functional tests, scenario tests,
 and live scenario tests.
 
-In most cases, only unit tests are required to validate changes. For large
-changes, functional or integration tests are often needed. In these cases,
-live scenario tests can be used to test end to end scenarios.
+Commonly, only unit tests are required to validate changes. For large
+changes, functional or integration tests are often needed. Live scenario tests can be used to test end to end scenarios for these larger changes.
 
 ## Unit tests
 
@@ -14,6 +13,11 @@ from the root of the repo run the following script:
 ./scripts/verify.sh local
 ```
 
+In Windows, use:
+```bash
+./scripts/verify.bat local
+```
+
 This command also runs PyLint to check code style.
 
 Unit tests should never depend on external connections or local resources such
@@ -22,14 +26,13 @@ never run for longer than a few seconds.
 
 ## Functional tests
 
-These tests currently check that the HTTP calls generated by calling an sfctl
-command is correct. It does this by calling the command against a mock cluster
-which is created by the test, and using VCR to record the transaction. The recorded
+These tests currently check that the HTTP requests generated by calling an sfctl
+command is correct. It verifies the request by calling the command against a mock cluster that is created by the test. The test then uses the module VCR to record the transaction. The recorded
 file is then read by the test to ensure correctness. The file is then deleted.
 
 These tests can be found in `<root>/src/sfctl/tests/request_generation_test.py`
 
-Any command which generates a HTTP request to the Service Fabric cluster should
+Any command that generates an HTTP request to the Service Fabric cluster should
 include at least one of these tests.
 
 ## Scenario tests
@@ -49,7 +52,7 @@ to connect to. The expected variable name is as follows:
 EXPORT SF_TEST_ENDPOINT=http://test.azure.com:19080
 ```
 
-In Windows, this is 
+In Windows, the command is 
 
 ```batch
 SET SF_TEST_ENDPOINT=http://test.azure.com:19080
@@ -73,8 +76,16 @@ to clean up any state if the test fails before subsequent runs.
 
 #### Enable
 
-Enable this test by specifying a path to a Service Fabric application package:
+Enable the application life cycle test by specifying a path to a Service Fabric application package:
 
 ```bash
 EXPORT SF_TEST_APP_PATH=/Users/test/Downloads/sample_apps/CalcApp/
-```
+```
+
+## Documentation tests
+
+Documentation tests serve two purposes: they ensure that errors do not occur when running the help command, and they ensure that all groups, commands, and arguments have descriptive text explaining their purpose. 
+
+These tests can be found in `<root>/src/sfctl/tests/help_text_test.py`.
+
+Add a test by adding or modifying an entry for the command validate_output. These commands are split into groups, and the name of each command in a group must be provided. Further details are documented in the test file.

Updating-sdk.md

@@ -1,17 +1,17 @@
 The Service Fabric CLI uses the underlying Azure Python SDK generated from
-Azure Service Fabric Open API (swagger) specifications.
+Azure Service Fabric Open API (Swagger) specifications.
 
 When making changes to the API specification, it is important to propagate all
-the changes to the CLI. This way, customers who use the CLI stay up to date.
+the changes from Swagger to the CLI. This way, customers who use the CLI stay current.
 
-Follow these steps to update the CLI when making changes to the API
+Follow these instructions to update the CLI when making changes to the API
 specifications.
 
 ## Required files
 
 Specifications are written using the Open API standard with Swagger. There
 is generally one `servicefabric.json` file or `servicefabric.yml` file that
-contains the entire specification.  In addition there may be some examples
+contains the entire specification.  In addition, there may be some examples
 in relative paths. Therefore you will need:
 
 - `servicefabric.json`, a single file with the full specification
@@ -20,7 +20,7 @@ in relative paths. Therefore you will need:
 ### For MS (internal) contributors
 
 For each new release of Service Fabric, these files can be found in a build of
-the SF-Swagger repository. This has commonly been
+the SF-Swagger repository. The path has commonly been
 `out\debug-AMD64\swagger-sfclient\<version>`, where `<version>` is the latest
 version available.
 
@@ -32,7 +32,7 @@ repository.
 The CLI uses the [data plane specification](https://github.com/Azure/azure-rest-api-specs/blob/current/specification/servicefabric/data-plane/Microsoft.ServiceFabric).
 
 Follow the standard contribution guidelines to update all the files to their
-latest version. This includes the examples and the main `servicefabric.json`
+latest version. Update includes the examples and the main `servicefabric.json`
 specification.
 
 ### Selecting a version
@@ -40,9 +40,9 @@ specification.
 If there are minor updates that are fixes for an existing Service Fabric
 runtime version, update the files in place.
 
-If the APIs are being updated for a major or minor release for a new Service
+When the APIs are being updated for a major or minor release for a new Service
 Fabric runtime version, create a subdirectory in the folder with the major,
-minor and build version number. So if this was a new release of Service Fabric
+minor, and build version number. If this release is a new release of Service Fabric
 10.0, the folder name should be `10.0`. If it is a new CU of an existing
 version, the folder name should be `10.0.1`.
 
@@ -57,7 +57,7 @@ create a new issue in the
 [python SDK repo](https://github.com/Azure/azure-sdk-for-python/).
 
 Someone will pick up the request and publish a new package. This package
-is commonly called `azure-servicefabric`. Once the package has been published
+is commonly called `azure-servicefabric`. Once the package has been published,
 it can be absorbed in the CLI.
 
 ## Switch to latest package in CLI

_Sidebar.md

@@ -14,7 +14,7 @@
   - [[Standard commands|Standard-commands]]
   - [[Command help strings|Command-help]]
   - [[Argument parsing|Command-params]]
-  - [[Updating SF Python SDK|Updating-sdk]]
+  - [[Updating and Publishing SF Python SDK|Updating-sdk]]
   - [[Client logic|Client-logic]]
 - Service Fabric Developers
   - [[Adding a command|Internal-development]]