diff options
author | Doug Hellmann <doug.hellmann@dreamhost.com> | 2014-06-09 15:15:30 -0400 |
---|---|---|
committer | Doug Hellmann <doug.hellmann@dreamhost.com> | 2014-06-23 08:18:21 -0700 |
commit | aec9e529fd72924cb8f3f149d35a6b9ce0581c81 (patch) | |
tree | 1ed463b18e482f15cb2f92d754c90b7bc351a9b2 | |
parent | 3f6b7424ffb6e576b50346f338d64cc5e8289e6a (diff) | |
download | oslotest-aec9e529fd72924cb8f3f149d35a6b9ce0581c81.tar.gz |
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
-rw-r--r-- | doc/source/api.rst | 23 | ||||
-rw-r--r-- | doc/source/index.rst | 2 | ||||
-rw-r--r-- | doc/source/usage.rst | 13 | ||||
-rw-r--r-- | oslotest/base.py | 40 | ||||
-rw-r--r-- | setup.cfg | 3 | ||||
-rw-r--r-- | tox.ini | 3 |
6 files changed, 70 insertions, 14 deletions
diff --git a/doc/source/api.rst b/doc/source/api.rst new file mode 100644 index 0000000..fc873d4 --- /dev/null +++ b/doc/source/api.rst @@ -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: diff --git a/doc/source/index.rst b/doc/source/index.rst index 97f5fd8..1bdc6d5 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -14,7 +14,7 @@ Contents: readme installation - usage + api contributing Indices and tables diff --git a/doc/source/usage.rst b/doc/source/usage.rst deleted file mode 100644 index a8ccdc4..0000000 --- a/doc/source/usage.rst +++ /dev/null @@ -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) diff --git a/oslotest/base.py b/oslotest/base.py index f84e810..f9c4b92 100644 --- a/oslotest/base.py +++ b/oslotest/base.py @@ -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 @@ -23,6 +23,9 @@ commands = [testenv:venv] commands = {posargs} +[testenv:docs] +commands = python setup.py build_sphinx + [flake8] show-source = True exclude = .tox,dist,doc,*.egg,build |