From d59543df4aef097b852a1c197a719904addbe552 Mon Sep 17 00:00:00 2001 From: Doug Hellmann Date: Wed, 10 Dec 2014 08:31:04 -0500 Subject: [PATCH] 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 | 1 - doc/source/api/fixture.lockutils.rst | 8 ++++++++ doc/source/api/index.rst | 7 +++++++ doc/source/api/lockutils.rst | 8 ++++++++ doc/source/api/opts.rst | 8 ++++++++ doc/source/api/processutils.rst | 8 ++++++++ doc/source/conf.py | 18 +----------------- doc/source/index.rst | 15 +++++++-------- doc/source/usage.rst | 26 +++++++++++++++++++++----- setup.cfg | 5 +---- 10 files changed, 69 insertions(+), 35 deletions(-) create mode 100644 doc/source/api/fixture.lockutils.rst create mode 100644 doc/source/api/index.rst create mode 100644 doc/source/api/lockutils.rst create mode 100644 doc/source/api/opts.rst create mode 100644 doc/source/api/processutils.rst diff --git a/.gitignore b/.gitignore index 7a8e0ab..1399c98 100644 --- a/.gitignore +++ b/.gitignore @@ -41,7 +41,6 @@ output/*/index.html # Sphinx doc/build -doc/source/api # pbr generates these AUTHORS 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 ` + +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 diff --git a/setup.cfg b/setup.cfg index 9f99301..2dbe018 100644 --- a/setup.cfg +++ b/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 -# want to treat sphinx warnings as errors -# warnerrors = True -autodoc_index_modules = True +warnerrors = True [wheel] universal = 1