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/conf.py

"""
import subprocess

from sphinx.util.console import bold, red

from cfme.utils.path import docs_path, 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', 'fixtures', 'markers', 'utils']
_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 # Shove stdout into a pipe to supress the output, but still let stderr out args = ['sphinx-apidoc', '-T', '-e', '-o', output_module_path, module_path, tests_exclude_path] proc = subprocess.Popen(args, stdout=subprocess.PIPE) proc.wait() 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: sphinx.info(bold('cleaning autogenerated docs... '), nonl=True) _doc_modules_path.ensure(dir=True) _doc_modules_path.remove(rec=True) sphinx.info(message='done') except Exception as ex: sphinx.info(red('failed to clean autogenerated docs')) sphinx.info(red(type(ex).__name__) + ' ', nonl=True) sphinx.info(str(ex))