Felipe Monteiro 0cd5d45706 Add sphinx job for auto-generating docs

Sphinx can be leveraged to auto-generate docs into feature-rich
HTML pages. Docstrings in modules and classes can be easily
auto-injected into documentation to produce high-level
documentation, yet with accompanying code blocks and
necessary docstrings.

This commit introduces the tox job for auto-generating docs,
as well as the foundational logic and documentation pages
(index, HACKING and glossary). While hacking rules are
introduced in HACKING.rst, they are not added in this
commit; that will be done in a follow-up patchset.

Additional documentation will also be included in a series
of future patchsets.

Change-Id: Iacd0e4542ebf481d66ab19dd43014b8d5bcc9e3f

2017-09-21 16:16:23 +01:00

3.2 KiB

Raw Blame History

Deckhand Style Commandments

Step 1: Read the OpenStack Style Commandments http://docs.openstack.org/developer/hacking/
Step 2: Read on

Deckhand Specific Commandments

[D316] Change assertTrue(isinstance(A, B)) by optimal assert like assertIsInstance(A, B).
[D317] Change assertEqual(type(A), B) by optimal assert like assertIsInstance(A, B).
[D320] Setting CONF.* attributes directly in tests is forbidden.
[D322] Method's default argument shouldn't be mutable.
[D324] Ensure that jsonutils.%(fun)s must be used instead of json.%(fun)s
[D325] str() and unicode() cannot be used on an exception. Remove use or use six.text_type()
[D334] Change assertTrue/False(A in/not in B, message) to the more specific assertIn/NotIn(A, B, message)
[D335] Check for usage of deprecated assertRaisesRegexp
[D336] Must use a dict comprehension instead of a dict constructor with a sequence of key-value pairs.
[D338] Change assertEqual(A in B, True), assertEqual(True, A in B), assertEqual(A in B, False) or assertEqual(False, A in B) to the more specific assertIn/NotIn(A, B)
[D339] Check common raise_feature_not_supported() is used for v2.1 HTTPNotImplemented response.
[D344] Python 3: do not use dict.iteritems.
[D345] Python 3: do not use dict.iterkeys.
[D346] Python 3: do not use dict.itervalues.
[D350] Policy registration should be in the central location deckhand/policies/.
[D352] LOG.warn is deprecated. Enforce use of LOG.warning.
[D355] Enforce use of assertTrue/assertFalse
[D356] Enforce use of assertIs/assertIsNot
[D357] Use oslo_utils.uuidutils or uuidsentinel(in case of test cases) to generate UUID instead of uuid4().
[D358] Return must always be followed by a space when returning a value.

Creating Unit Tests

For every new feature, unit tests should be created that both test and (implicitly) document the usage of said feature. If submitting a patch for a bug that had no unit test, a new passing unit test should be added. If a submitted bug fix does have a unit test, be sure to add a new one that fails without the patch and passes with the patch.

Running Tests

The testing system is based on a combination of tox and testr. The canonical approach to running tests is to simply run the command tox. This will create virtual environments, populate them with dependencies and run all of the tests that OpenStack CI systems run. Behind the scenes, tox is running testr run --parallel, but is set up such that you can supply any additional testr arguments that are needed to tox. For example, you can run: tox -- --analyze-isolation to cause tox to tell testr to add --analyze-isolation to its argument list.

Functional testing leverages gabbi and requires docker as a prerequisite to be run. Functional tests can be executing by running the command tox -e functional.

Building Docs

Normal Sphinx docs can be built via the setuptools build_sphinx command. To do this via tox, simply run tox -e docs, which will cause a virtualenv with all of the needed dependencies to be created and then inside of the virtualenv, the docs will be created and put into doc/build/html.