[core] undo help.yaml changes in #8325, #8503 and #8535

doc/authoring_help.md

@@ -12,20 +12,11 @@ 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<br>
-	    **or** <br>
-	    src/command_modules/azure-cli-**[module name]**/azure/cli/command_modules/**[module name]**/help.yaml
+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.  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>
@@ -74,72 +65,6 @@ 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.
@@ -168,8 +93,7 @@ Here are the layers of Project Az help, with each layer overriding the layer bel
 
 | Help Display                  |
 |-------------------------------|
-| YAML Authoring via *help.yaml*|
-| YAML Authoring via *_help.py* |
+| YAML Authoring (_help.py)   |
 | Code Specified                |
 | Docstring                     |
 | SDK Text                      |
@@ -213,20 +137,6 @@ The first example is only supported on the `latest` and `2018-03-01-hybrid` prof
           supported-profiles: 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
-          supported-profiles: latest, 2018-03-01-hybrid
-          # alternatively 
-          # supported-profiles: latest, 2018-03-01-hybrid
-        - 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
-          supported-profiles: 2017-03-09-profile
-```
-
 Here is how this looks in CLI `--help`:
 
 On profiles `latest` and `2018-03-01-hybrid`.

doc/sphinx/azhelpgen/azhelpgen.py

@@ -9,10 +9,11 @@
 from os.path import expanduser
 from docutils import nodes
 from docutils.statemachine import ViewList
+
+# Directive not in latest release of sphinx, need to pip install sphinx==1.6.7
 from sphinx.util.compat import Directive
 from sphinx.util.nodes import nested_parse_with_titles
 
-
 from azure.cli.core import MainCommandsLoader, AzCli
 from azure.cli.core.commands import AzCliCommandInvoker
 from azure.cli.core.parser import AzCliCommandParser
@@ -88,14 +89,14 @@ def make_rst(self):
                             pass
                         yield '{}:default: {}'.format(DOUBLEINDENT, arg.default)
                     if arg.value_sources:
-                        yield '{}:source: {}'.format(DOUBLEINDENT, ', '.join(_get_populator_commands(arg)))
+                        yield '{}:source: {}'.format(DOUBLEINDENT, ', '.join(arg.value_sources))
                     yield ''
             yield ''
             if len(help_file.examples) > 0:
                for e in help_file.examples:
-                  yield '{}.. cliexample:: {}'.format(INDENT, e.short_summary)
+                  yield '{}.. cliexample:: {}'.format(INDENT, e.name)
                   yield ''
-                  yield DOUBLEINDENT + e.command.replace("\\", "\\\\")
+                  yield DOUBLEINDENT + e.text.replace("\\", "\\\\")
                   yield ''
 
     def run(self):
@@ -108,37 +109,11 @@ def run(self):
         nested_parse_with_titles(self.state, result, node)
         return node.children
 
+
 def setup(app):
     app.add_directive('azhelpgen', AzHelpGenDirective)
 
 
-def _store_parsers(parser, parser_keys, parser_values, sub_parser_keys, sub_parser_values):
-    for s in parser.subparsers.values():
-        parser_keys.append(_get_parser_name(s))
-        parser_values.append(s)
-        if _is_group(s):
-            for c in s.choices.values():
-                sub_parser_keys.append(_get_parser_name(c))
-                sub_parser_values.append(c)
-                _store_parsers(c, parser_keys, parser_values, sub_parser_keys, sub_parser_values)
-
 def _load_doc_source_map():
     with open('azhelpgen/doc_source_map.json') as open_file:
         return json.load(open_file)
-
-def _is_group(parser):
-    return getattr(parser, '_subparsers', None) is not None \
-        or getattr(parser, 'choices', None) is not None
-
-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