Add docs target and generate api docs

Once we use the pbr based build to generate files, we prune
the indexes to remove references to code we would like to
hide like the common modules and private modules in conf.py.
We reuse the same excluded_patterns variable that is already
used in Sphinx and filter these modules from autoindex.rst

Closes-Bug: #1364140

Change-Id: I5767e429e63935f055a6f4e82349224ccfa2f497

5 files changed, 34 insertions, 1 deletions

diff --git a/doc/source/conf.py b/doc/source/conf.py
index 1567379..4342b35 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -13,6 +13,8 @@
 
 import os
 import sys
+import fileinput
+import fnmatch
 
 sys.path.insert(0, os.path.abspath('../..'))
 # -- General configuration ----------------------------------------------------
@@ -29,6 +31,23 @@ extensions = [
 # text edit cycles.
 # execute "export SPHINX_DEBUG=1" in your terminal to disable
 
+# A list of glob-style patterns that should be excluded when looking for source
+# files.
+exclude_patterns = [
+    'api/tests.*',  # avoid of docs generation from tests
+    'api/oslo.vmware.openstack.common.*',  # skip common modules
+    'api/oslo.vmware._*',  # skip private modules
+]
+
+# Prune the excluded patterns from the autoindex
+for line in fileinput.input('api/autoindex.rst', inplace=True):
+    found = False
+    for pattern in exclude_patterns:
+        if fnmatch.fnmatch(line, '*' + pattern[4:]):
+            found = True
+    if not found:
+        print line,
+
 # The suffix of source filenames.
 source_suffix = '.rst'
 
diff --git a/doc/source/index.rst b/doc/source/index.rst
index acb1078..a120c1a 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -11,6 +11,14 @@ Contents:
    usage
    contributing
 
+Code Documentation
+==================
+
+.. toctree::
+   :maxdepth: 1
+
+   api/autoindex
+
 Indices and tables
 ==================
 
diff --git a/setup.cfg b/setup.cfg
index 7d93433..f4b9024 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -46,3 +46,6 @@ input_file = oslo.vmware/locale/oslo.vmware.pot
 keywords = _ gettext ngettext l_ lazy_gettext
 mapping_file = babel.cfg
 output_file = oslo.vmware/locale/oslo.vmware.pot
+
+[pbr]
+autodoc_index_modules = 1
diff --git a/test-requirements.txt b/test-requirements.txt
index 6217181..4ecc93b 100644
--- a/test-requirements.txt
+++ b/test-requirements.txt
@@ -17,5 +17,5 @@ testtools>=0.9.34
 coverage>=3.6
 
 # this is required for the docs build jobs
-sphinx>=1.1.2,!=1.2.0,<1.3
 oslosphinx>=2.2.0.0a2
+sphinx>=1.1.2,!=1.2.0,<1.3
diff --git a/tox.ini b/tox.ini
index 06e8ab6..054293d 100644
--- a/tox.ini
+++ b/tox.ini
@@ -15,6 +15,9 @@ commands = flake8
 [testenv:pylint]
 commands = pylint oslo
 
+[testenv:docs]
+commands = python setup.py build_sphinx
+
 [testenv:cover]
 setenv = VIRTUAL_ENV={envdir}
 commands =