0cd5d45706
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
68 lines
3.2 KiB
ReStructuredText
68 lines
3.2 KiB
ReStructuredText
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.
|