Use sphinxcontrib-apidoc for building api docs

This is the preferred method for building api docs now.

Change-Id: Id05341fa00ae250980a769375cd68f10d3d752b3

oslo.{{cookiecutter.module_name}}/doc/requirements.txt

@@ -5,3 +5,4 @@
 sphinx!=1.6.6,!=1.6.7,>=1.6.2,<2.0.0;python_version=='2.7' # BSD
 sphinx!=1.6.6,!=1.6.7,>=1.6.2;python_version>='3.4' # BSD
 openstackdocstheme>=1.20.0
+sphinxcontrib-apidoc>=0.2.0 # BSD

oslo.{{cookiecutter.module_name}}/doc/source/api.rst

@@ -1,12 +0,0 @@
-=====
- API
-=====
-
-.. Use autodoc directives to describe the *public* modules and classes
-   in the library.
-
-   If the modules are completely unrelated, create an api subdirectory
-   and use a separate file for each (see oslo.utils).
-
-   If there is only one submodule, a single api.rst file like this
-   sufficient (see oslo.i18n).

oslo.{{cookiecutter.module_name}}/doc/source/conf.py

@@ -22,6 +22,8 @@ sys.path.insert(0, os.path.abspath('../..'))
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     'openstackdocstheme',
+    'sphinxcontrib.apidoc',
+
 ]
 
 repository_name = 'openstack/oslo.{{cookiecutter.module_name}}'
@@ -69,5 +71,12 @@ latex_documents = [
      u'OpenStack Foundation', 'manual'),
 ]
 
-# Example configuration for intersphinx: refer to the Python standard library.
-#intersphinx_mapping = {'http://docs.python.org/': None}
+# -- sphinxcontrib.apidoc configuration --------------------------------------
+
+apidoc_module_dir = '../../'
+apidoc_output_dir = 'reference/api'
+apidoc_excluded_paths = [
+    'oslo_{{cookiecutter.module_name}}/tests',
+    'oslo_{{cookiecutter.module_name}}/_*',
+    'setup.py',
+]

oslo.{{cookiecutter.module_name}}/doc/source/index.rst

@@ -11,7 +11,7 @@ Contents
    :maxdepth: 2
 
    installation
-   api
+   reference/index
    usage
    contributing
    history

oslo.{{cookiecutter.module_name}}/doc/source/reference/index.rst

@@ -0,0 +1,13 @@
+.. _using:
+
+=========
+Reference
+=========
+
+API
+===
+
+.. toctree::
+   :maxdepth: 1
+
+   api/modules

oslo.{{cookiecutter.module_name}}/tox.ini

@@ -38,7 +38,11 @@ commands =
     coverage xml -o cover/coverage.xml
 
 [testenv:docs]
-commands = sphinx-build -W -b html doc/source doc/build/html
+whitelist_externals =
+    rm
+commands =
+    rm -rf doc/build doc/source/reference/api
+    sphinx-build -W -b html doc/source doc/build/html
 deps =
     -c{env:UPPER_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master}
     -r{toxinidir}/doc/requirements.txt