Source code for cfme.utils.apidoc

"""Sphinx plugin for automatically generating (and optionally cleaning) project api documentation

To enable the optional cleaning, set ``clean_autogenerated_docs`` to ``True`` in docs/

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:"cleaning autogenerated docs ...") _doc_modules_path.ensure(dir=True) _doc_modules_path.remove(rec=True)"done") except Exception: logger.exception("failed to clean autogenerated docs")