Merge "Adding sphinx extension for CLI docs autogeneration"

doc/ext/cli.py

@@ -0,0 +1,90 @@
+# Copyright (c) 2015 Mirantis Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+import inspect
+import os
+import sys
+
+from docutils import nodes
+from sphinxarg import ext
+
+
+def _get_command(classes):
+    """Associates each command class with command depending on setup.cfg
+    """
+    commands = {}
+    setup_file = os.path.join(
+        os.path.abspath(os.path.join(os.path.dirname(__file__), '../..')),
+        'setup.cfg')
+    for line in open(setup_file, 'r'):
+        for cl in classes:
+            if cl in line:
+                commands[cl] = line.split(' = ')[0].strip().replace('_', ' ')
+
+    return commands
+
+
+class ArgParseDirectiveOSC(ext.ArgParseDirective):
+    """Sphinx extension that automatically documents commands and options
+    of the module that contains OpenstackClient/cliff command objects
+
+    Usage example:
+
+    .. cli::
+       :module: saharaclient.osc.v1.clusters
+
+    """
+    def run(self):
+        module_name = self.options['module']
+
+        mod = __import__(module_name, globals(), locals())
+
+        classes = inspect.getmembers(sys.modules[module_name], inspect.isclass)
+        classes_names = [cl[0] for cl in classes]
+        commands = _get_command(classes_names)
+
+        items = []
+
+        for cl in classes:
+            parser = cl[1](None, None).get_parser(None)
+            parser.prog = commands[cl[0]]
+            items.append(nodes.subtitle(text=commands[cl[0]]))
+            result = ext.parse_parser(
+                parser, skip_default_values='nodefault' in self.options)
+            result = ext.parser_navigate(result, '')
+            nested_content = ext.nodes.paragraph()
+            self.state.nested_parse(
+                self.content, self.content_offset, nested_content)
+            nested_content = nested_content.children
+
+            for item in nested_content:
+                if not isinstance(item, ext.nodes.definition_list):
+                    items.append(item)
+            if 'description' in result:
+                items.append(self._nested_parse_paragraph(result['description']))
+            items.append(ext.nodes.literal_block(text=result['usage']))
+            items.append(ext.print_command_args_and_opts(
+                ext.print_arg_list(result, nested_content),
+                ext.print_opt_list(result, nested_content),
+                ext.print_subcommand_list(result, nested_content)
+            ))
+            if 'epilog' in result:
+                items.append(self._nested_parse_paragraph(result['epilog']))
+        return items
+
+
+def setup(app):
+    app.add_directive('cli', ArgParseDirectiveOSC)

doc/source/cli.rst

@@ -0,0 +1,64 @@
+Sahara CLI Commands
+===================
+
+The following commands are currently supported by the Sahara CLI:
+
+Plugins
+-------
+
+.. cli::
+   :module: saharaclient.osc.v1.plugins
+
+Images
+------
+
+.. cli::
+   :module: saharaclient.osc.v1.images
+
+Node Group Templates
+--------------------
+
+.. cli::
+   :module: saharaclient.osc.v1.node_group_templates
+
+Cluster Templates
+-----------------
+
+.. cli::
+   :module: saharaclient.osc.v1.cluster_templates
+
+Clusters
+--------
+
+.. cli::
+   :module: saharaclient.osc.v1.clusters
+
+Data Sources
+------------
+
+.. cli::
+   :module: saharaclient.osc.v1.data_sources
+
+Job Binaries
+------------
+
+.. cli::
+   :module: saharaclient.osc.v1.job_binaries
+
+Job Types
+---------
+
+.. cli::
+   :module: saharaclient.osc.v1.job_types
+
+Job Templates
+-------------
+
+.. cli::
+   :module: saharaclient.osc.v1.job_templates
+
+Jobs
+----
+
+.. cli::
+   :module: saharaclient.osc.v1.jobs

doc/source/conf.py

@@ -36,8 +36,9 @@ sys.path.append(os.path.abspath('../bin'))
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo', 'sphinx.ext.coverage',
-              'sphinx.ext.pngmath', 'sphinx.ext.viewcode']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo',
+              'sphinx.ext.coverage', 'sphinx.ext.pngmath',
+              'sphinx.ext.viewcode', 'ext.cli']
 
 if not on_rtd:
     extensions.append('oslosphinx')

doc/source/index.rst

@@ -22,6 +22,7 @@ Contents:
 
    api
    shell
+   cli
    how_to_participate
 
 Contributing

doc/source/shell.rst

@@ -20,6 +20,9 @@ To get detailed help for the command you can run:
 
     $ openstack help dataprocessing <command>
 
+For more information about commands and their parameters you can refer to
+:doc:`the Sahara CLI commands <cli>`.
+
 For more information about abilities and features of OpenStackClient CLI you
 can refer to `OpenStackClient documentation <http://docs.openstack.org/developer/python-openstackclient/>`_
 

tox.ini

@@ -12,6 +12,7 @@ setenv =
 deps =
     -r{toxinidir}/requirements.txt
     -r{toxinidir}/test-requirements.txt
+    sphinx-argparse
 commands = bash tools/pretty_tox.sh "{posargs}"
 whitelist_externals = bash
 passenv = http_proxy HTTP_PROXY https_proxy HTTPS_PROXY no_proxy NO_PROXY