Clean up API documentation

Use explicit files instead of auto-generating them.

Fail the build on a warning.

Tweak titles and other headings.

Add instructions for using lockutils-wrapper.

Change-Id: Ie92ce14b33180d35d84bbd0998e61b659487481d

8 files changed, 68 insertions, 30 deletions

diff --git a/doc/source/api/fixture.lockutils.rst b/doc/source/api/fixture.lockutils.rst
new file mode 100644
index 0000000..8f82f40
--- /dev/null
+++ b/doc/source/api/fixture.lockutils.rst
@@ -0,0 +1,8 @@
+===========================================
+ :mod:`oslo_concurrency.fixture.lockutils`
+===========================================
+
+.. automodule:: oslo_concurrency.fixture.lockutils
+  :members:
+  :undoc-members:
+  :show-inheritance:
diff --git a/doc/source/api/index.rst b/doc/source/api/index.rst
new file mode 100644
index 0000000..33aadc4
--- /dev/null
+++ b/doc/source/api/index.rst
@@ -0,0 +1,7 @@
+.. toctree::
+   :maxdepth: 1
+
+   fixture.lockutils
+   lockutils
+   opts
+   processutils
diff --git a/doc/source/api/lockutils.rst b/doc/source/api/lockutils.rst
new file mode 100644
index 0000000..76a37fa
--- /dev/null
+++ b/doc/source/api/lockutils.rst
@@ -0,0 +1,8 @@
+===================================
+ :mod:`oslo_concurrency.lockutils`
+===================================
+
+.. automodule:: oslo_concurrency.lockutils
+  :members:
+  :undoc-members:
+  :show-inheritance:
diff --git a/doc/source/api/opts.rst b/doc/source/api/opts.rst
new file mode 100644
index 0000000..8972b27
--- /dev/null
+++ b/doc/source/api/opts.rst
@@ -0,0 +1,8 @@
+==============================
+ :mod:`oslo_concurrency.opts`
+==============================
+
+.. automodule:: oslo_concurrency.opts
+  :members:
+  :undoc-members:
+  :show-inheritance:
diff --git a/doc/source/api/processutils.rst b/doc/source/api/processutils.rst
new file mode 100644
index 0000000..787095c
--- /dev/null
+++ b/doc/source/api/processutils.rst
@@ -0,0 +1,8 @@
+======================================
+ :mod:`oslo_concurrency.processutils`
+======================================
+
+.. automodule:: oslo_concurrency.processutils
+  :members:
+  :undoc-members:
+  :show-inheritance:
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 2d42847..edd0343 100755
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -34,23 +34,7 @@ extensions = [
 
 # 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.*',  # skip deprecated import from namespace package
-    'api/oslo_concurrency.openstack.common.*',  # skip common modules
-    'api/oslo_concurrency._*',  # skip private modules
-]
-
-# Prune the excluded patterns from the autoindex
-PATH = 'api/autoindex.rst'
-if os.path.isfile(PATH) and os.access(PATH, os.R_OK):
-    for line in fileinput.input(PATH, inplace=True):
-        found = False
-        for pattern in exclude_patterns:
-            if fnmatch.fnmatch(line, '*' + pattern[4:]):
-                found = True
-        if not found:
-            print line,
+exclude_patterns = []
 
 # The suffix of source filenames.
 source_suffix = '.rst'
diff --git a/doc/source/index.rst b/doc/source/index.rst
index b2ef8cf..8d1757f 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -3,13 +3,12 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to oslo.concurrency's documentation!
-===============================================================
-
-Contents:
+==================
+ oslo.concurrency
+==================
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    readme
    installation
@@ -17,13 +16,13 @@ Contents:
    contributing
    history
 
-Code Documentation
-==================
+API Documentation
+=================
 
 .. toctree::
    :maxdepth: 1
 
-   api/autoindex
+   api/index
 
 Indices and tables
 ==================
diff --git a/doc/source/usage.rst b/doc/source/usage.rst
index 5be4f08..f438151 100644
--- a/doc/source/usage.rst
+++ b/doc/source/usage.rst
@@ -1,7 +1,23 @@
-========
-Usage
-========
+=======
+ Usage
+=======
 
-To use oslo.concurrency in a project::
+To use oslo.concurrency in a project, import the relevant module. For
+example::
 
-    from oslo import concurrency
\ No newline at end of file
+    from oslo_concurrency import lockutils
+
+.. seealso::
+
+   * :doc:`API Documentation <api/index>`
+
+Command Line Wrapper
+====================
+
+``oslo.concurrency`` includes a command line tool for use in test jobs
+that need the environment variable :envvar:`OSLO_LOCK_PATH` set. To
+use it, prefix the command to be run with
+:command:`lockutils-wrapper`. For example::
+
+  $ lockutils-wrapper env | grep OSLO_LOCK_PATH
+  OSLO_LOCK_PATH=/tmp/tmpbFHK45