From 3a09189098f19724a896566fa962b26653e85f89 Mon Sep 17 00:00:00 2001 From: Doug Hellmann Date: Wed, 23 Jul 2014 16:05:59 -0400 Subject: [PATCH] Add API docs and clean up other docs Add auto-generated documentation for the public modules in the library and clean up a bit of the docstrings used. Change-Id: Id5efa5c413b82e13f1a7ac78c92e39c193f12214 --- CONTRIBUTING.rst | 2 +- doc/source/api/encodeutils.rst | 6 ++++++ doc/source/api/excutils.rst | 6 ++++++ doc/source/api/importutils.rst | 6 ++++++ doc/source/api/index.rst | 9 +++++++++ doc/source/api/netutils.rst | 6 ++++++ doc/source/api/strutils.rst | 6 ++++++ doc/source/api/timeutils.rst | 6 ++++++ doc/source/api/units.rst | 6 ++++++ doc/source/contributing.rst | 6 +++++- doc/source/index.rst | 1 + doc/source/readme.rst | 2 +- doc/source/usage.rst | 13 ++++++++----- oslo/utils/netutils.py | 4 +++- setup.cfg | 3 +++ tox.ini | 3 +++ 16 files changed, 76 insertions(+), 9 deletions(-) create mode 100644 doc/source/api/encodeutils.rst create mode 100644 doc/source/api/excutils.rst create mode 100644 doc/source/api/importutils.rst create mode 100644 doc/source/api/index.rst create mode 100644 doc/source/api/netutils.rst create mode 100644 doc/source/api/strutils.rst create mode 100644 doc/source/api/timeutils.rst create mode 100644 doc/source/api/units.rst diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 6d30824..88b16aa 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -14,4 +14,4 @@ Pull requests submitted through GitHub will be ignored. Bugs should be filed on Launchpad, not GitHub: - https://bugs.launchpad.net/oslo.utils \ No newline at end of file + https://bugs.launchpad.net/oslo diff --git a/doc/source/api/encodeutils.rst b/doc/source/api/encodeutils.rst new file mode 100644 index 0000000..82ca596 --- /dev/null +++ b/doc/source/api/encodeutils.rst @@ -0,0 +1,6 @@ +============= + encodeutils +============= + +.. automodule:: oslo.utils.encodeutils + :members: diff --git a/doc/source/api/excutils.rst b/doc/source/api/excutils.rst new file mode 100644 index 0000000..d39be38 --- /dev/null +++ b/doc/source/api/excutils.rst @@ -0,0 +1,6 @@ +========== + excutils +========== + +.. automodule:: oslo.utils.excutils + :members: diff --git a/doc/source/api/importutils.rst b/doc/source/api/importutils.rst new file mode 100644 index 0000000..0864d92 --- /dev/null +++ b/doc/source/api/importutils.rst @@ -0,0 +1,6 @@ +============= + importutils +============= + +.. automodule:: oslo.utils.importutils + :members: diff --git a/doc/source/api/index.rst b/doc/source/api/index.rst new file mode 100644 index 0000000..f193e3b --- /dev/null +++ b/doc/source/api/index.rst @@ -0,0 +1,9 @@ +===== + API +===== + +.. toctree:: + :maxdepth: 2 + :glob: + + * diff --git a/doc/source/api/netutils.rst b/doc/source/api/netutils.rst new file mode 100644 index 0000000..bb50442 --- /dev/null +++ b/doc/source/api/netutils.rst @@ -0,0 +1,6 @@ +========== + netutils +========== + +.. automodule:: oslo.utils.netutils + :members: diff --git a/doc/source/api/strutils.rst b/doc/source/api/strutils.rst new file mode 100644 index 0000000..bd2531b --- /dev/null +++ b/doc/source/api/strutils.rst @@ -0,0 +1,6 @@ +========== + strutils +========== + +.. automodule:: oslo.utils.strutils + :members: diff --git a/doc/source/api/timeutils.rst b/doc/source/api/timeutils.rst new file mode 100644 index 0000000..d1292b3 --- /dev/null +++ b/doc/source/api/timeutils.rst @@ -0,0 +1,6 @@ +=========== + timeutils +=========== + +.. automodule:: oslo.utils.timeutils + :members: diff --git a/doc/source/api/units.rst b/doc/source/api/units.rst new file mode 100644 index 0000000..edd1bed --- /dev/null +++ b/doc/source/api/units.rst @@ -0,0 +1,6 @@ +======= + units +======= + +.. automodule:: oslo.utils.units + :members: diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index 8cb3146..2ca75d1 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -1 +1,5 @@ -.. include:: ../../CONTRIBUTING.rst \ No newline at end of file +============== + Contributing +============== + +.. include:: ../../CONTRIBUTING.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index 211999d..720896a 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -9,6 +9,7 @@ Contents: readme installation usage + api/index contributing Indices and tables diff --git a/doc/source/readme.rst b/doc/source/readme.rst index 6b2b3ec..a6210d3 100644 --- a/doc/source/readme.rst +++ b/doc/source/readme.rst @@ -1 +1 @@ -.. include:: ../README.rst \ No newline at end of file +.. include:: ../../README.rst diff --git a/doc/source/usage.rst b/doc/source/usage.rst index 35bb227..9e83f6b 100644 --- a/doc/source/usage.rst +++ b/doc/source/usage.rst @@ -1,7 +1,10 @@ -======== -Usage -======== +========= + Usage +========= -To use oslo.utils in a project:: +To use oslo.utils in a project, import the individual module you +need. For example:: - import oslo.utils \ No newline at end of file + from oslo.utils import strutils + + slug = strutils.to_slug('input value') diff --git a/oslo/utils/netutils.py b/oslo/utils/netutils.py index 27b1fab..f9e6beb 100644 --- a/oslo/utils/netutils.py +++ b/oslo/utils/netutils.py @@ -95,7 +95,9 @@ class ModifiedSplitResult(parse.SplitResult): def urlsplit(url, scheme='', allow_fragments=True): """Parse a URL using urlparse.urlsplit(), splitting query and fragments. - This function papers over Python issue9374 when needed. + This function papers over Python issue9374_ when needed. + + .. _issue9374: http://bugs.python.org/issue9374 The parameters are the same as urlparse.urlsplit. """ diff --git a/setup.cfg b/setup.cfg index fb1e954..9aaf088 100644 --- a/setup.cfg +++ b/setup.cfg @@ -25,6 +25,9 @@ packages = namespace_packages = oslo +[pbr] +warnerrors = true + [build_sphinx] source-dir = doc/source build-dir = doc/build diff --git a/tox.ini b/tox.ini index de8ba05..7a492ff 100644 --- a/tox.ini +++ b/tox.ini @@ -22,6 +22,9 @@ commands = flake8 [testenv:venv] commands = {posargs} +[testenv:docs] +commands = python setup.py build_sphinx + [testenv:cover] commands = python setup.py testr --coverage --testr-args='{posargs}'