"""Sphinx plugin for automatically generating (and optionally cleaning) project api documentation
To enable the optional cleaning, set ``clean_autogenerated_docs`` to ``True`` in docs/conf.py
"""
from sphinx.ext import apidoc
from cfme.utils.log import logger
from cfme.utils.path import docs_path
from cfme.utils.path import project_path
# When adding/removing from this list, remember to edit docs/modules.rst to match
#: List of modules/packages to document, paths relative to the project root.
modules_to_document = ['cfme']
_doc_modules_path = docs_path.join('modules')
[docs]def setup(sphinx):
"""Main sphinx entry point, calls sphinx-apidoc"""
for module in modules_to_document:
module_path = project_path.join(module).strpath
tests_exclude_path = project_path.join(module, 'tests').strpath
output_module_path = _doc_modules_path.join(module).strpath
args = [
'-T',
'-e',
'-o',
output_module_path,
module_path,
tests_exclude_path
]
apidoc.main(args)
sphinx.add_config_value('clean_autogenerated_docs', False, rebuild='')
sphinx.connect('build-finished', purge_module_apidoc)
[docs]def purge_module_apidoc(sphinx, exception):
# Short out if not supposed to run
if not sphinx.config.clean_autogenerated_docs:
return
try:
logger.info("cleaning autogenerated docs ...")
_doc_modules_path.ensure(dir=True)
_doc_modules_path.remove(rec=True)
logger.info("done")
except Exception:
logger.exception("failed to clean autogenerated docs")