From 6dc128636e6161851272d534d47dfbd422f65161 Mon Sep 17 00:00:00 2001
From: Steve Martinelli <stevemar@ca.ibm.com>
Date: Tue, 18 Nov 2014 00:16:21 -0500
Subject: [PATCH] Enhance the theming for modules page

Also fixes a few small docstring syntax errors

Change-Id: I85eb968e32c1191cf5d60d02deff2ab7f3291074
---
 .gitignore                               |  2 ++
 doc/ext/__init__.py                      |  0
 doc/ext/apidoc.py                        | 43 ++++++++++++++++++++++++
 doc/source/conf.py                       |  8 ++++-
 doc/source/index.rst                     |  4 +--
 openstackclient/api/api.py               |  1 +
 openstackclient/common/commandmanager.py |  2 +-
 7 files changed, 56 insertions(+), 4 deletions(-)
 create mode 100644 doc/ext/__init__.py
 create mode 100644 doc/ext/apidoc.py

diff --git a/.gitignore b/.gitignore
index 84079f2f9f..5dc75afa47 100644
--- a/.gitignore
+++ b/.gitignore
@@ -15,7 +15,9 @@ AUTHORS
 build
 ChangeLog
 dist
+# Doc related
 doc/build
+doc/source/api/
 # Development environment files
 .project
 .pydevproject
diff --git a/doc/ext/__init__.py b/doc/ext/__init__.py
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/doc/ext/apidoc.py b/doc/ext/apidoc.py
new file mode 100644
index 0000000000..5e18385a6d
--- /dev/null
+++ b/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)
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 7c7a00b313..e805a98767 100644
--- a/doc/source/conf.py
+++ b/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']
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 0f92b3f018..a3c6516d30 100644
--- a/doc/source/index.rst
+++ b/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`
diff --git a/openstackclient/api/api.py b/openstackclient/api/api.py
index 72a66e1cb4..67386aaf0b 100644
--- a/openstackclient/api/api.py
+++ b/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')
         """
diff --git a/openstackclient/common/commandmanager.py b/openstackclient/common/commandmanager.py
index 2d9575d9d2..b34bf7d6f3 100644
--- a/openstackclient/common/commandmanager.py
+++ b/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):