Enhance the theming for modules page

Also fixes a few small docstring syntax errors

Change-Id: I85eb968e32c1191cf5d60d02deff2ab7f3291074

.gitignore

@@ -15,7 +15,9 @@ AUTHORS
 build
 ChangeLog
 dist
+# Doc related
 doc/build
+doc/source/api/
 # Development environment files
 .project
 .pydevproject

doc/ext/apidoc.py

@@ -0,0 +1,43 @@
+# Copyright 2014 OpenStack Foundation
+#
+# 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 os.path as path
+
+from sphinx import apidoc
+
+
+# NOTE(blk-u): pbr will run Sphinx multiple times when it generates
+# documentation. Once for each builder. To run this extension we use the
+# 'builder-inited' hook that fires at the beginning of a Sphinx build.
+# We use ``run_already`` to make sure apidocs are only generated once
+# even if Sphinx is run multiple times.
+run_already = False
+
+
+def run_apidoc(app):
+    global run_already
+    if run_already:
+        return
+    run_already = True
+
+    package_dir = path.abspath(path.join(app.srcdir, '..', '..',
+                                         'openstackclient'))
+    source_dir = path.join(app.srcdir, 'api')
+    apidoc.main(['apidoc', package_dir, '-f',
+                 '-H', 'openstackclient Modules',
+                 '-o', source_dir])
+
+
+def setup(app):
+    app.connect('builder-inited', run_apidoc)

doc/source/conf.py

@@ -22,6 +22,10 @@ import pbr.version
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..')))
 
+# NOTE(blk-u): Path for our Sphinx extension, remove when
+# https://launchpad.net/bugs/1260495 is fixed.
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))
+
 # -- General configuration ----------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -32,7 +36,9 @@ sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..',
 extensions = ['sphinx.ext.autodoc',
               'sphinx.ext.doctest',
               'sphinx.ext.todo',
-              'oslosphinx']
+              'oslosphinx',
+              'ext.apidoc',
+              ]
 
 # Add any paths that contain templates here, relative to this directory.
 #templates_path = ['_templates']

doc/source/index.rst

@@ -37,8 +37,8 @@ the openstack/python-openstackclient project using `Gerrit`_.
 .. _Launchpad: https://launchpad.net/python-openstackclient
 .. _Gerrit: http://wiki.openstack.org/GerritWorkflow
 
-Index
+Indices and Tables
-=====
+==================
 
 * :ref:`genindex`
 * :ref:`modindex`

openstackclient/api/api.py

@@ -227,6 +227,7 @@ class BaseAPI(KeystoneSession):
             attribute to use for resource search
         :param string resource:
             plural of the object resource name; defaults to path
+
         For example:
             n = find(netclient, 'network', 'networks', 'matrix')
         """

openstackclient/common/commandmanager.py

@@ -28,7 +28,7 @@ class CommandManager(cliff.commandmanager.CommandManager):
     """Add additional functionality to cliff.CommandManager
 
     Load additional command groups after initialization
-    Add *_command_group() methods
+    Add _command_group() methods
     """
 
     def __init__(self, namespace, convert_underscores=True):