Add code/api documentation

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

Change-Id: I4baea1efa227ef14bc6706d59ff3dcad93c2eacc
Closes-Bug: #1364140

doc/source/conf.py

@@ -14,6 +14,8 @@
 
 import os
 import sys
+import fileinput
+import fnmatch
 
 sys.path.insert(0, os.path.abspath('../..'))
 # -- General configuration ----------------------------------------------------
@@ -30,6 +32,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.concurrency.openstack.common.*',  # skip common modules
+    'api/oslo.concurrency._*',  # 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'
 

doc/source/index.rst

@@ -16,6 +16,14 @@ Contents:
    usage
    contributing
 
+Code Documentation
+==================
+
+.. toctree::
+   :maxdepth: 1
+
+   api/autoindex
+
 Indices and tables
 ==================
 

setup.cfg

@@ -47,3 +47,9 @@ input_file = oslo.concurrency/locale/oslo.concurrency.pot
 keywords = _ gettext ngettext l_ lazy_gettext
 mapping_file = babel.cfg
 output_file = oslo.concurrency/locale/oslo.concurrency.pot
+
+[pbr]
+# NOTE(dims): uncomment ``warnerrors`` line, when
+# want to treat sphinx warnings as errors
+# warnerrors = True
+autodoc_index_modules = True

test-requirements.txt

@@ -2,5 +2,5 @@ hacking>=0.9.1,<0.10
 oslotest
 
 # These are needed for docs generation
-oslosphinx
+oslosphinx>=2.2.0.0a2
 sphinx>=1.1.2,!=1.2.0,<1.3