Fix python-openstackclient plugin doc build

A help string in a plugin command argument help string contained (a typo
and) some invalid sphinx-isms causing autoprogram-cliff building from
python-openstackclient to fail with:

.../python-openstackclient/doc/source/cli/plugin-commands/watcher.rst:30:Inline emphasis start-string without end-string.
and
<CreateAuditTemplate>:1:Unexpected indentation.

This commit fixes the (typo and) help string formatting.

Change-Id: Ifb668b9ada94b679672f3bab562410bf12f4ca64

doc/source/conf.py

@@ -88,6 +88,17 @@ latex_documents = [
     ),
 ]
 
+# Disable usage of xindy https://bugzilla.redhat.com/show_bug.cgi?id=1643664
+latex_use_xindy = False
+
+latex_domain_indices = False
+
+latex_elements = {
+    'makeindex': '',
+    'printindex': '',
+    'preamble': r'\setcounter{tocdepth}{3}',
+}
+
 # openstackdocstheme options
 repository_name = 'openstack/python-watcherclient'
 bug_project = 'python-watcherclient'

tox.ini

@@ -48,6 +48,18 @@ deps =
   -r{toxinidir}/doc/requirements.txt
 commands = python setup.py build_sphinx
 
+[testenv:pdf-docs]
+basepython = python3
+envdir = {toxworkdir}/docs
+deps = {[testenv:docs]deps}
+whitelist_externals =
+  rm
+  make
+commands =
+  rm -rf doc/build/pdf
+  sphinx-build -W -b latex doc/source doc/build/pdf
+  make -C doc/build/pdf
+
 [testenv:debug]
 basepython = python3
 commands = oslo_debug_helper -t watcherclient/tests/unit {posargs}

watcherclient/v1/audit_shell.py

@@ -182,7 +182,7 @@ class CreateAudit(command.ShowOne):
             dest='interval',
             metavar='<interval>',
             help=_('Audit interval (in seconds or cron format). '
-                   'Cron inteval can be used like: "*/5 * * * *". '
+                   'Cron interval can be used like: ``*/5 * * * *``. '
                    'Only used if the audit is CONTINUOUS.'))
         parser.add_argument(
             '-g', '--goal',

watcherclient/v1/audit_template_shell.py

@@ -167,8 +167,8 @@ class CreateAuditTemplate(command.ShowOne):
             metavar='<path>',
             help=_("Part of the cluster on which an audit will be done.\n"
                    "Can be provided either in yaml or json file.\n"
-                   "YAML example:\n"
-                   "---\n"
+                   "YAML example::\n"
+                   "\n"
                    " - compute:\n"
                    "   - host_aggregates:\n"
                    "     - id: 1\n"
@@ -201,48 +201,49 @@ class CreateAuditTemplate(command.ShowOne):
                    "       - uuid: UUID1\n"
                    "       - uuid: UUID2\n"
                    "\n"
-                   "JSON example:\n"
-                   "[\n"
-                   " {\"compute\":\n"
-                   "      [{\"host_aggregates\": [\n"
-                   "            {\"id\": 1},\n"
-                   "            {\"id\": 2},\n"
-                   "            {\"id\": 3}]},\n"
-                   "       {\"availability_zones\": [\n"
-                   "            {\"name\": \"AZ1\"},\n"
-                   "            {\"name\": \"AZ2\"}]},\n"
-                   "       {\"exclude\": [\n"
-                   "            {\"instances\": [\n"
-                   "                 {\"uuid\": \"UUID1\"},\n"
-                   "                 {\"uuid\": \"UUID2\"}\n"
-                   "            ]},\n"
-                   "            {\"compute_nodes\": [\n"
-                   "                 {\"name\": \"compute1\"}\n"
-                   "            ]}\n"
-                   "       ]}]\n"
-                   "  },\n"
-                   " {\"storage\":\n"
-                   "      [{\"availability_zones\": [\n"
-                   "            {\"name\": \"AZ1\"},\n"
-                   "            {\"name\": \"AZ2\"}]},\n"
-                   "       {\"volume_types\": [\n"
-                   "            {\"name\": \"lvm1\"},\n"
-                   "            {\"name\": \"lvm2\"}]},\n"
-                   "       {\"exclude\": [\n"
-                   "            {\"storage_pools\": [\n"
-                   "                 {\"name\": \"host0@backend0#pool0\"},\n"
-                   "                 {\"name\": \"host1@backend1#pool1\"}\n"
-                   "            ]},\n"
-                   "            {\"volumes\": [\n"
-                   "                 {\"uuid\": \"UUID1\"},\n"
-                   "                 {\"uuid\": \"UUID2\"}\n"
-                   "            ]},\n"
-                   "            {\"projects\": [\n"
-                   "                 {\"uuid\": \"UUID1\"},\n"
-                   "                 {\"uuid\": \"UUID2\"}\n"
-                   "            ]},\n"
-                   "       ]}]\n"
-                   "  }\n"
+                   "JSON example::\n"
+                   "\n"
+                   " [\n"
+                   "  {\"compute\":\n"
+                   "       [{\"host_aggregates\": [\n"
+                   "             {\"id\": 1},\n"
+                   "             {\"id\": 2},\n"
+                   "             {\"id\": 3}]},\n"
+                   "        {\"availability_zones\": [\n"
+                   "             {\"name\": \"AZ1\"},\n"
+                   "             {\"name\": \"AZ2\"}]},\n"
+                   "        {\"exclude\": [\n"
+                   "             {\"instances\": [\n"
+                   "                  {\"uuid\": \"UUID1\"},\n"
+                   "                  {\"uuid\": \"UUID2\"}\n"
+                   "             ]},\n"
+                   "             {\"compute_nodes\": [\n"
+                   "                  {\"name\": \"compute1\"}\n"
+                   "             ]}\n"
+                   "        ]}]\n"
+                   "   },\n"
+                   "  {\"storage\":\n"
+                   "       [{\"availability_zones\": [\n"
+                   "             {\"name\": \"AZ1\"},\n"
+                   "             {\"name\": \"AZ2\"}]},\n"
+                   "        {\"volume_types\": [\n"
+                   "             {\"name\": \"lvm1\"},\n"
+                   "             {\"name\": \"lvm2\"}]},\n"
+                   "        {\"exclude\": [\n"
+                   "             {\"storage_pools\": [\n"
+                   "                  {\"name\": \"host0@backend0#pool0\"},\n"
+                   "                  {\"name\": \"host1@backend1#pool1\"}\n"
+                   "             ]},\n"
+                   "             {\"volumes\": [\n"
+                   "                  {\"uuid\": \"UUID1\"},\n"
+                   "                  {\"uuid\": \"UUID2\"}\n"
+                   "             ]},\n"
+                   "             {\"projects\": [\n"
+                   "                  {\"uuid\": \"UUID1\"},\n"
+                   "                  {\"uuid\": \"UUID2\"}\n"
+                   "             ]},\n"
+                   "        ]}]\n"
+                   "   }\n"
                    " ]\n"
                    )
         )