In addition to PEP 257, inline documentation of the cfme_tests code adheres to the Google Python Style Guide. The Google-recommended docstring format is very easy to both read and write, and thanks to the cartouche library, it’s parseable by sphinx, which we use to generate our documentation.
The napoleon library parses our docstrings and turns them into nicely rendered API docs in the sphinx output. As such, we should follow napoleon’s usage guidelines when writing docstrings:
According to PEP 257, docstrings should use triple double-quotes, not triple single-quotes (“”” vs. ‘’’).
"""This is a docstring.""" '''This is not a docstring.'''
Tests are documented slightly differently to modules, in that they require certain extra information that isn’t required for a module/class/function. If a test uses the testgen library it must also specify a test_flag in the metadata section. An example of this is shown below.
"""Tests provisioning via PXE Metadata: test_flag: pxe, provision """
These flags are also defined in the
cfme_data.yaml file, under the
test_flags: key. A
provider in the
cfme_data.yaml can opt out of collection for a particular test_flag by
including the flag in the list of
excluded_test_flags: key in the providers stanza.
All of the flags listings are listed in comma separated format. This was chosen to cut down on
syntax characters and all values are whitespace stripped.
- For a test to be collected for a provider:
the test_flag must be listed in the
the test_flag must be listed in the metadata section of the test’s docstring
the test_flag must NOT appear in the list of
excluded_test_flags:for a particular provider
It is beneficial that the documented test also has its description in it in Google-style format. When the automated tests get imported in our test case management system, the comment is imported as a description, so you don’t have to write it twice!
"""Tests provisioning via PXE This test verifies that foo causes bar to crash. Prerequisities: * bar is set up * baz Steps: 1) Ook. 2) Ook? 3) Ook! Metadata: test_flag: pxe, provision """
Building the Docs¶
Prior to pushing up new code, preview any new documentation by building to docs locally.
You can do this using the sphinx-build command. From the
sphinx-build -b html docs/ docs/build/
This will build html documentation based on the sources in the docs/ directory, and put them in the docs/build/ directory, which can then be opened in a browser:
google-chrome docs/build/index.html # or... firefox docs/build/index.html