diff --git a/source/sphinx_extensions/plugin_directory/extension.py b/source/sphinx_extensions/plugin_directory/extension.py index c53d11c8..13e46a6f 100644 --- a/source/sphinx_extensions/plugin_directory/extension.py +++ b/source/sphinx_extensions/plugin_directory/extension.py @@ -9,12 +9,22 @@ import os import os.path import shutil +import subprocess +import textwrap import jinja2 import qiime2.sdk def generate_rst(app): + app.info("Generating QIIME 2 plugin directory... (this may take awhile)") + + # Refresh the CLI cache just in case it is out of date with what's + # installed (this should only affect packages while they are installed in + # development mode). The CLI is used below to generate some of the help + # text. + subprocess.run(['qiime', 'dev', 'refresh-cache'], check=True) + plugins = qiime2.sdk.PluginManager().plugins loader = jinja2.PackageLoader('sphinx_extensions.plugin_directory', 'templates') @@ -32,47 +42,41 @@ def generate_rst(app): fh.write(rendered) for plugin in plugins.values(): - plugin_dir = os.path.join(rst_dir, plugin.name) + plugin_cli_name = plugin.name.replace('_', '-') + plugin_dir = os.path.join(rst_dir, plugin_cli_name) os.mkdir(plugin_dir) index_path = os.path.join(plugin_dir, 'index.rst') with open(index_path, 'w') as fh: template = env.get_template('plugin.rst') - rendered = template.render(plugin=plugin) + rendered = template.render(title=plugin_cli_name, plugin=plugin) fh.write(rendered) for action in plugin.actions.values(): - action_path = os.path.join(plugin_dir, '%s.rst' % action.id) - with open(action_path, 'w') as fh: - title = '%s: %s' % (action.id, action.name) + action_cli_name = action.id.replace('_', '-') + action_path = os.path.join(plugin_dir, '%s.rst' % action_cli_name) - input_specs = _get_param_specs(action.signature, 'inputs') - parameter_specs = _get_param_specs(action.signature, - 'parameters') - output_specs = _get_param_specs(action.signature, 'outputs', - no_default='N/A') + with open(action_path, 'w') as fh: + title = '%s: %s' % (action_cli_name, action.name) + directive_indent = ' ' * 3 + + app.info("Generating help text for `%s %s`..." % + (plugin_cli_name, action_cli_name)) + command = ['qiime', plugin_cli_name, action_cli_name, '--help'] + proc = subprocess.run(command, check=True, + stdout=subprocess.PIPE, + stderr=subprocess.STDOUT) + cli_help = textwrap.indent(proc.stdout.decode('utf-8'), + directive_indent).strip() + api_help = textwrap.indent(action.__call__.__doc__, + directive_indent).strip() template = env.get_template('action.rst') - rendered = template.render(action=action, title=title, - input_specs=input_specs, - parameter_specs=parameter_specs, - output_specs=output_specs) + rendered = template.render(title=title, cli_help=cli_help, + api_help=api_help) fh.write(rendered) -def _get_param_specs(signature, group, no_default='Required'): - specs = [] - for name, spec in getattr(signature, group).items(): - default = no_default - if spec.has_default(): - default = spec.default - description = 'No description' - if spec.has_description(): - description = spec.description - specs.append((name, spec.qiime_type, default, description)) - return specs - - def cleanup_rst(app, exception): if hasattr(app, 'plugin_directory_rst_dir') and \ os.path.exists(app.plugin_directory_rst_dir): diff --git a/source/sphinx_extensions/plugin_directory/templates/action.rst b/source/sphinx_extensions/plugin_directory/templates/action.rst index deccaa43..268e2741 100644 --- a/source/sphinx_extensions/plugin_directory/templates/action.rst +++ b/source/sphinx_extensions/plugin_directory/templates/action.rst @@ -1,48 +1,23 @@ {{ title }} {{ '=' * title|length }} -{{ action.description }} - .. raw:: html -
{{ group }} | -|||
---|---|---|---|
Name | -Type | -Default | -Description | -
N/A | -|||
-
- {{ content }}
-
- |
- {% endfor %}
-
- {% for line in spec[3].splitlines() %}
- {{ line|urlize }} - {% endfor %} - |
-
+ {{- cli_help -}} ++
+ {{- api_help -}} ++