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

.gitignore

@@ -41,7 +41,6 @@ output/*/index.html
 
 # Sphinx
 doc/build
-doc/source/api
 
 # pbr generates these
 AUTHORS

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:

doc/source/api/index.rst

@@ -0,0 +1,7 @@
+.. toctree::
+   :maxdepth: 1
+
+   fixture.lockutils
+   lockutils
+   opts
+   processutils

doc/source/api/lockutils.rst

@@ -0,0 +1,8 @@
+===================================
+ :mod:`oslo_concurrency.lockutils`
+===================================
+
+.. automodule:: oslo_concurrency.lockutils
+  :members:
+  :undoc-members:
+  :show-inheritance:

doc/source/api/opts.rst

@@ -0,0 +1,8 @@
+==============================
+ :mod:`oslo_concurrency.opts`
+==============================
+
+.. automodule:: oslo_concurrency.opts
+  :members:
+  :undoc-members:
+  :show-inheritance:

doc/source/api/processutils.rst

@@ -0,0 +1,8 @@
+======================================
+ :mod:`oslo_concurrency.processutils`
+======================================
+
+.. automodule:: oslo_concurrency.processutils
+  :members:
+  :undoc-members:
+  :show-inheritance:

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 = [
+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,
 
 # The suffix of source filenames.
 source_suffix = '.rst'

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!
+==================
-===============================================================
+ oslo.concurrency
-
+==================
-Contents:
 
 .. 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
 ==================

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
+    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

setup.cfg

@@ -58,10 +58,7 @@ mapping_file = babel.cfg
 output_file = oslo.concurrency/locale/oslo.concurrency.pot
 
 [pbr]
-# NOTE(dims): uncomment ``warnerrors`` line, when
+warnerrors = True
-# want to treat sphinx warnings as errors
-# warnerrors = True
-autodoc_index_modules = True
 
 [wheel]
 universal = 1