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/

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']
_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:'cleaning autogenerated docs... '), nonl=True) _doc_modules_path.ensure(dir=True) _doc_modules_path.remove(rec=True)'done') except Exception as ex:'failed to clean autogenerated docs')) + ' ', nonl=True)