Ref doc gen formatting improvements (#116)

* Ref doc gen: Format user directory as ~ and use forward slashes * fix exceptions * Preserve backslashes in example text
Azure · Mar 30, 2018 · e229279 · e229279
1 parent 9e53cd9
commit e229279
Showing 1 changed file with 29 additions and 21 deletions.
diff --git a/scripts/refdoc/azhelpgen/azhelpgen.py b/scripts/refdoc/azhelpgen/azhelpgen.py
@@ -5,6 +5,7 @@
 
 import argparse
 import json
+from os.path import expanduser
 from docutils import nodes
 from docutils.statemachine import ViewList
 from docutils.parsers.rst import Directive
@@ -18,6 +19,8 @@
 from azure.cli.core.parser import AzCliCommandParser
 from azure.cli.core._help import AzCliHelp, CliCommandHelpFile, ArgumentGroupRegistry
 
+USER_HOME = expanduser('~')
+
 
 def get_extension_help_files(cli_ctx):
     invoker = cli_ctx.invocation_cls(cli_ctx=cli_ctx, commands_loader_cls=cli_ctx.commands_loader_cls,
@@ -78,33 +81,38 @@ def make_rst(self):
                for arg in sorted(help_file.parameters,
                                 key=lambda p: group_registry.get_group_priority(p.group_name)
                                 + str(not p.required) + p.name):
-                  yield '{}.. cliarg:: {}'.format(INDENT, arg.name)
-                  yield ''
-                  yield '{}:required: {}'.format(DOUBLEINDENT, arg.required)
-                  short_summary = arg.short_summary or ''
-                  possible_values_index = short_summary.find(' Possible values include')
-                  short_summary = short_summary[0:possible_values_index
+                    yield '{}.. cliarg:: {}'.format(INDENT, arg.name)
+                    yield ''
+                    yield '{}:required: {}'.format(DOUBLEINDENT, arg.required)
+                    short_summary = arg.short_summary or ''
+                    possible_values_index = short_summary.find(' Possible values include')
+                    short_summary = short_summary[0:possible_values_index
                                                 if possible_values_index >= 0 else len(short_summary)]
-                  short_summary = short_summary.strip()
-                  yield '{}:summary: {}'.format(DOUBLEINDENT, short_summary)
-                  yield '{}:description: {}'.format(DOUBLEINDENT, arg.long_summary)
-                  if arg.choices:
-                     yield '{}:values: {}'.format(DOUBLEINDENT, ', '.join(sorted([str(x) for x in arg.choices])))
-                  if arg.default and arg.default != argparse.SUPPRESS:
-                     try:
-                         arg.default = arg.default.replace("\\", "\\\\")
-                     except Exception:
-                         pass
-                     yield '{}:default: {}'.format(DOUBLEINDENT, arg.default)
-                  if arg.value_sources:
-                     yield '{}:source: {}'.format(DOUBLEINDENT, ', '.join(arg.value_sources))
-                  yield ''
+                    short_summary = short_summary.strip()
+                    yield '{}:summary: {}'.format(DOUBLEINDENT, short_summary)
+                    yield '{}:description: {}'.format(DOUBLEINDENT, arg.long_summary)
+                    if arg.choices:
+                        yield '{}:values: {}'.format(DOUBLEINDENT, ', '.join(sorted([str(x) for x in arg.choices])))
+                    if arg.default and arg.default != argparse.SUPPRESS:
+                        try:
+                            if arg.default.startswith(USER_HOME):
+                                arg.default = arg.default.replace(USER_HOME, '~').replace('\\', '/')
+                        except Exception:
+                            pass
+                        try:
+                            arg.default = arg.default.replace("\\", "\\\\")
+                        except Exception:
+                            pass
+                        yield '{}:default: {}'.format(DOUBLEINDENT, arg.default)
+                    if arg.value_sources:
+                        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.name)
                   yield ''
-                  yield DOUBLEINDENT + e.text
+                  yield DOUBLEINDENT + e.text.replace("\\", "\\\\")
                   yield ''
 
     def run(self):