Source code for henson.contrib.sphinx

"""Sphinx contrib plugin for documenting Henson CLI extensions."""

from sphinxcontrib.autoprogram import AutoprogramDirective


def _import_extension(import_path):
    module_name, extension_name = import_path.split(':', 1)
    module = __import__(module_name, None, None, [extension_name])
    return getattr(module, extension_name)


[docs]class HensonCLIDirective(AutoprogramDirective): """A Sphinx directive that can be used to document a CLI extension. This class wraps around `autoprogram <https://pythonhosted.org/sphinxcontrib-autoprogram/>`_ to generate Sphinx documentation for extensions that extend the Henson CLI. .. code:: .. hensoncli:: henson_database:Database :start_command: db .. versionadded:: 1.1.0 .. versionchanged:: 1.2.0 The ``prog`` option will default to the proper way to invoke command line extensions. """ def prepare_autoprogram(self): """Prepare the instance to be run through autoprogram.""" # Tell autoprogram how to find the argument parser. self.arguments = 'henson.cli:parser', # Most Henson CLI extensions will be invoked the same way. The # extension authors shouldn't have to include that in their # Sphinx documentation. self.options.setdefault('prog', 'henson --app APP_PATH') def register_cli(self): """Register the CLI.""" import_path, = self.arguments extension = _import_extension(import_path) extension().register_cli() def run(self): """Register the CLI and run autoprogram.""" self.register_cli() self.prepare_autoprogram() return super().run()
def setup(app): """Register the extension.""" app.add_directive('hensoncli', HensonCLIDirective)