Add API documentation
Add docstrings and sphinx structure to expose them through the developer docs for the library. Also add a 'docs' target in tox.ini to make building the documentation locally easier. Remove the nearly useless usage.rst file. Turn on the pbr flag to treat doc build warnings as errors. Closes-bug: #1329952 Change-Id: I274a4144edf4efe9ed786e220e40003fda6f99e0
This commit is contained in:
parent
3f6b7424ff
commit
aec9e529fd
|
@ -0,0 +1,23 @@
|
||||||
|
=====
|
||||||
|
API
|
||||||
|
=====
|
||||||
|
|
||||||
|
oslotest.base
|
||||||
|
=============
|
||||||
|
|
||||||
|
.. automodule:: oslotest.base
|
||||||
|
|
||||||
|
.. autoclass:: oslotest.base.BaseTestCase
|
||||||
|
:members:
|
||||||
|
|
||||||
|
oslotest.mockpatch
|
||||||
|
==================
|
||||||
|
|
||||||
|
.. automodule:: oslotest.mockpatch
|
||||||
|
:members:
|
||||||
|
|
||||||
|
oslotest.moxstubout
|
||||||
|
===================
|
||||||
|
|
||||||
|
.. automodule:: oslotest.moxstubout
|
||||||
|
:members:
|
|
@ -14,7 +14,7 @@ Contents:
|
||||||
|
|
||||||
readme
|
readme
|
||||||
installation
|
installation
|
||||||
usage
|
api
|
||||||
contributing
|
contributing
|
||||||
|
|
||||||
Indices and tables
|
Indices and tables
|
||||||
|
|
|
@ -1,13 +0,0 @@
|
||||||
========
|
|
||||||
Usage
|
|
||||||
========
|
|
||||||
|
|
||||||
To use in a project::
|
|
||||||
|
|
||||||
from oslotest import base
|
|
||||||
|
|
||||||
|
|
||||||
class MyTest(base.BaseTestCase):
|
|
||||||
|
|
||||||
def test_something(self):
|
|
||||||
self.assertTrue(True)
|
|
|
@ -28,6 +28,38 @@ _LOG_FORMAT = "%(levelname)8s [%(name)s] %(message)s"
|
||||||
|
|
||||||
|
|
||||||
class BaseTestCase(testtools.TestCase):
|
class BaseTestCase(testtools.TestCase):
|
||||||
|
"""Base class for unit test classes.
|
||||||
|
|
||||||
|
If the environment variable ``OS_TEST_TIMEOUT`` is set to an
|
||||||
|
integer value, a timer is configured to control how long
|
||||||
|
individual test cases can run. This lets tests fail for taking too
|
||||||
|
long, and prevents deadlocks from completely hanging test runs.
|
||||||
|
|
||||||
|
If the environment variable ``OS_STDOUT_CAPTURE`` is set, a fake
|
||||||
|
stream replaces ``sys.stdout`` so the test can look at the output
|
||||||
|
it produces.
|
||||||
|
|
||||||
|
If the environment variable ``OS_STDERR_CAPTURE`` is set, a fake
|
||||||
|
stream replaces ``sys.stderr`` so the test can look at the output
|
||||||
|
it produces.
|
||||||
|
|
||||||
|
If the environment variable ``OS_DEBUG`` is set to a true value,
|
||||||
|
debug logging is enabled.
|
||||||
|
|
||||||
|
If the environment variable ``OS_LOG_CAPTURE`` is set to a true
|
||||||
|
value, a logging fixture is installed to capture the log output.
|
||||||
|
|
||||||
|
Uses the fixtures_ module to configure a :class:`NestedTempFile`
|
||||||
|
to ensure that all temporary files are created in an isolated
|
||||||
|
location.
|
||||||
|
|
||||||
|
Uses the fixtures_ module to configure a :class:`TempHomeDir` to
|
||||||
|
change the ``HOME`` environment variable to point to a temporary
|
||||||
|
location.
|
||||||
|
|
||||||
|
.. _fixtures: https://pypi.python.org/pypi/fixtures
|
||||||
|
|
||||||
|
"""
|
||||||
|
|
||||||
def setUp(self):
|
def setUp(self):
|
||||||
super(BaseTestCase, self).setUp()
|
super(BaseTestCase, self).setUp()
|
||||||
|
@ -73,6 +105,14 @@ class BaseTestCase(testtools.TestCase):
|
||||||
logging.basicConfig(format=_LOG_FORMAT, level=level)
|
logging.basicConfig(format=_LOG_FORMAT, level=level)
|
||||||
|
|
||||||
def create_tempfiles(self, files, ext='.conf'):
|
def create_tempfiles(self, files, ext='.conf'):
|
||||||
|
"""Safely create temporary files.
|
||||||
|
|
||||||
|
:param files: Sequence of tuples containing (filename, file_contents).
|
||||||
|
:type files: list of tuple
|
||||||
|
:param ext: File name extension for the temporary file.
|
||||||
|
:type ext: str
|
||||||
|
:return: A list of str with the names of the files created.
|
||||||
|
"""
|
||||||
tempfiles = []
|
tempfiles = []
|
||||||
for (basename, contents) in files:
|
for (basename, contents) in files:
|
||||||
if not os.path.isabs(basename):
|
if not os.path.isabs(basename):
|
||||||
|
|
|
@ -34,3 +34,6 @@ all_files = 1
|
||||||
|
|
||||||
[upload_sphinx]
|
[upload_sphinx]
|
||||||
upload-dir = doc/build/html
|
upload-dir = doc/build/html
|
||||||
|
|
||||||
|
[pbr]
|
||||||
|
warnerrors = true
|
||||||
|
|
3
tox.ini
3
tox.ini
|
@ -23,6 +23,9 @@ commands =
|
||||||
[testenv:venv]
|
[testenv:venv]
|
||||||
commands = {posargs}
|
commands = {posargs}
|
||||||
|
|
||||||
|
[testenv:docs]
|
||||||
|
commands = python setup.py build_sphinx
|
||||||
|
|
||||||
[flake8]
|
[flake8]
|
||||||
show-source = True
|
show-source = True
|
||||||
exclude = .tox,dist,doc,*.egg,build
|
exclude = .tox,dist,doc,*.egg,build
|
||||||
|
|
Loading…
Reference in New Issue