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
23
doc/source/api.rst
Normal file
23
doc/source/api.rst
Normal file
@ -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
|
||||
installation
|
||||
usage
|
||||
api
|
||||
contributing
|
||||
|
||||
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):
|
||||
"""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):
|
||||
super(BaseTestCase, self).setUp()
|
||||
@ -73,6 +105,14 @@ class BaseTestCase(testtools.TestCase):
|
||||
logging.basicConfig(format=_LOG_FORMAT, level=level)
|
||||
|
||||
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 = []
|
||||
for (basename, contents) in files:
|
||||
if not os.path.isabs(basename):
|
||||
|
@ -34,3 +34,6 @@ all_files = 1
|
||||
|
||||
[upload_sphinx]
|
||||
upload-dir = doc/build/html
|
||||
|
||||
[pbr]
|
||||
warnerrors = true
|
||||
|
Loading…
Reference in New Issue
Block a user