Help Authoring Updates.

doc/authoring_help.md

@@ -12,11 +12,20 @@ To override help for a given command:
 	1. Search code base for "account clear".
 	2. Search result: src/command_modules/azure-cli-**profile**/azure/cli/command_modules/**profile**/commands.py.
 	3. Result shows "account clear" is in the "profile" module.
-2. Using the module name, find the YAML help file which follows the path pattern:
-	1.  src/command_modules/azure-cli-**[module name]**/azure/cli/command_modules/**[module name]**/_help.py.
+2. Using the module name, find the YAML help file which follows the path pattern.:
+	1.  src/command_modules/azure-cli-**[module name]**/azure/cli/command_modules/**[module name]**/_help.py<br>
+	    **or** <br>
+	    src/command_modules/azure-cli-**[module name]**/azure/cli/command_modules/**[module name]**/help.yaml
 	2.  If the file doesn't exist, it can be created.
 3.  Find or create a help entry with the name of the command/group you want to document.  See example below.
 
+
+>  ###Notes: <br>
+>  1. If using **_help.py** files for help authoring, the command module's **\_\_init\_\_.py** file must import the **_help.py** file. i.e: <br>
+>    `import azure.cli.command_modules.examplemod._help` <br>
+>  2. The Help Authoring System now supports **help.yaml** files. Eventually, **_help.py** files will be replaced by **help.yaml**.
+
+
 ### Example YAML help file, _help.py ###
 
 <pre>
@@ -25,7 +34,7 @@ To override help for a given command:
 # Licensed under the MIT License. See License.txt in the project root for license information.
 #---------------------------------------------------------------------------------------------
 
-from azure.cli.help_files import helps
+from knack.help_files import helps
 
 #pylint: disable=line-too-long
 
@@ -65,6 +74,72 @@ helps['account'] = """
             """
 </pre>
 
+
+### Example YAML help file, help.yaml (Version 1) ###
+<pre>
+#---------------------------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for license information.
+#---------------------------------------------------------------------------------------------
+
+version: 1
+
+content:
+
+- command:
+    name: account clear
+    summary: Clear account
+    description: Longer summary of how the dummy account clear command works
+    links:
+      - title: Azure Accounts Webpage
+        url: https://azure.microsoft.com/en-us/account/
+      - url: https://aka.ms/just-a-url
+    arguments:
+      - name: --account-name
+        summary: Account name
+        description: |
+          Longer summary with newlines preserved.
+          Preserving newlines is helpful for paragraph breaks.
+        value-sources:
+          - link:
+              title: List accounts
+              command: az account list
+          - link:
+              title: Show an accounts details
+              command: az account show
+          - link:
+              title: Azure Accounts Webpage
+              url: https://azure.microsoft.com/en-us/account/
+          - link:
+              title: Azure Billing Documentation
+              url: https://docs.microsoft.com/en-us/azure/billing/
+          - string:
+              "Account name should be lower case with no numbers or special symbol."
+    examples:
+    - summary: Clear an account
+      description: >
+        This is a longer description of the example.
+        The > character collapses multiple lines into a single line,
+        which is good for on-screen wrapping.
+      command: |
+        az account clear --acount-name myaccount
+
+</pre>
+
+You can also document groups using a similar format.
+
+<pre>
+
+- group:
+    name: account
+    summary: Manage Azure accounts
+    description: Longer summary of the account command group
+    links:
+      - title: Azure Accounts Webpage
+        url: https://azure.microsoft.com/en-us/account/
+      - url: https://aka.ms/just-a-url
+</pre>
+
 # Tips to write effective help for your command
 
 - Make sure the doc contains all the details that someone unfamiliar with the API needs to use the command.
@@ -91,12 +166,13 @@ Command help starts with its raw SDK docstring text, if available.  Non-SDK comm
 
 Here are the layers of Project Az help, with each layer overriding the layer below it:
 
-| Help Display   |
-|----------------|
-| YAML Authoring |
-| Code Specified |
-| Docstring      |
-| SDK Text       |
+| Help Display                  |
+|-------------------------------|
+| YAML Authoring via *help.yaml*|
+| YAML Authoring via *_help.py* |
+| Code Specified                |
+| Docstring                     |
+| SDK Text                      |
 
 ## Page titles for command groups ##
 
@@ -123,6 +199,8 @@ For command examples, you optionally specify the profile the example is for with
 Here's a samply for `storage account create`:  
 The first example is only supported on the profile `latest` and above whilst the second example if only supported on `2017-03-09-profile` and below.
 
+### _help.py
+
 ```
     examples:
         - name: Create a storage account MyStorageAccount in resource group MyResourceGroup in the West US region with locally redundant storage.
@@ -133,6 +211,18 @@ The first example is only supported on the profile `latest` and above whilst the
           max_profile: 2017-03-09-profile
 ```
 
+### help.yaml
+
+```
+    examples:
+        - summary: Create a storage account MyStorageAccount in resource group MyResourceGroup in the West US region with locally redundant storage.
+          command: az storage account create -n MyStorageAccount -g MyResourceGroup -l westus --sku Standard_LRS
+          min_profile: latest
+        - summary: Create a storage account MyStorageAccount in resource group MyResourceGroup in the West US region with locally redundant storage.
+          command: az storage account create -n MyStorageAccount -g MyResourceGroup -l westus --account-type Standard_LRS
+          max_profile: 2017-03-09-profile
+```
+
 Here is how this looks in CLI `--help`:
 
 On profile `latest`.

doc/sphinx/azhelpgen/azhelpgen.py

@@ -12,7 +12,6 @@
 from sphinx.util.compat import Directive
 from sphinx.util.nodes import nested_parse_with_titles
 
-from knack.help_files import helps
 
 from azure.cli.core import MainCommandsLoader, AzCli
 from azure.cli.core.commands import AzCliCommandInvoker
@@ -89,14 +88,14 @@ def make_rst(self):
                             pass
                         yield '{}:default: {}'.format(DOUBLEINDENT, arg.default)
                     if arg.value_sources:
-                        yield '{}:source: {}'.format(DOUBLEINDENT, ', '.join(arg.value_sources))
+                        yield '{}:source: {}'.format(DOUBLEINDENT, ', '.join(_get_populator_commands(arg)))
                     yield ''
             yield ''
             if len(help_file.examples) > 0:
                for e in help_file.examples:
-                  yield '{}.. cliexample:: {}'.format(INDENT, e.name)
+                  yield '{}.. cliexample:: {}'.format(INDENT, e.short_summary)
                   yield ''
-                  yield DOUBLEINDENT + e.text.replace("\\", "\\\\")
+                  yield DOUBLEINDENT + e.command.replace("\\", "\\\\")
                   yield ''
 
     def run(self):
@@ -133,3 +132,13 @@ def _is_group(parser):
 
 def _get_parser_name(s):
     return (s._prog_prefix if hasattr(s, '_prog_prefix') else s.prog)[3:]
+
+
+def _get_populator_commands(param):
+    commands = []
+    for value_source in param.value_sources:
+        try:
+            commands.append(value_source["link"]["command"])
+        except KeyError:
+            continue
+    return commands

scripts/ci/precheck_header.sh

@@ -23,3 +23,4 @@ python -m automation.tests.verify_readme_history
 #    python -m automation.tests.verify_package_versions --base-repo $latestCliReleaseDir --base-tag $latestCliReleaseTag
 # fi
 
+