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 - - {% for group, specs in (('Inputs', input_specs), - ('Parameters', parameter_specs), - ('Outputs', output_specs)) %} - - - - - {% if specs %} - - - - - - - {% else %} - - - - {% endif %} - - - {% for spec in specs %} - - {% for content in spec[:3] %} - - {% endfor %} - - - {% endfor %} - - {% endfor %} -
{{ group }}
NameTypeDefaultDescription
N/A
- - {{ content }} - - - {% for line in spec[3].splitlines() %} - {{ line|urlize }}
- {% endfor %} -
+
+ +
+
+
+           {{- cli_help -}}
+         
+
+
+
+           {{- api_help -}}
+         
+
+
+
diff --git a/source/sphinx_extensions/plugin_directory/templates/available.rst b/source/sphinx_extensions/plugin_directory/templates/available.rst index 13726dd4..cacb1992 100644 --- a/source/sphinx_extensions/plugin_directory/templates/available.rst +++ b/source/sphinx_extensions/plugin_directory/templates/available.rst @@ -7,10 +7,10 @@ QIIME 2 microbiome analysis functionality is made available to users via plugins :maxdepth: 3 {% for name, plugin in plugins|dictsort %} + {% set cli_name = name.replace('_', '-') %} {% if plugin.short_description %} - {{ name }}: {{ plugin.short_description }} <{{ name }}/index> + {{ cli_name }}: {{ plugin.short_description }} <{{ cli_name }}/index> {% else %} - {{ name }}/index + {{ cli_name }}/index {% endif %} {% endfor %} - diff --git a/source/sphinx_extensions/plugin_directory/templates/plugin.rst b/source/sphinx_extensions/plugin_directory/templates/plugin.rst index 534f5cba..c218fb4c 100644 --- a/source/sphinx_extensions/plugin_directory/templates/plugin.rst +++ b/source/sphinx_extensions/plugin_directory/templates/plugin.rst @@ -1,5 +1,5 @@ -{{ plugin.name }} -{{ '=' * plugin.name|length }} +{{ title }} +{{ '=' * title|length }} .. raw:: html @@ -8,9 +8,9 @@ Description - {% for line in plugin.description.splitlines() %} - {{ line|urlize }}
- {% endfor %} + {% for line in plugin.description.splitlines() %} + {{ line|urlize }}
+ {% endfor %} @@ -48,7 +48,7 @@ Methods :maxdepth: 1 {% for id, _ in plugin.methods|dictsort %} - {{ id }} + {{ id.replace('_', '-') }} {% endfor %} {% else %} This plugin does not have any methods. @@ -62,7 +62,7 @@ Visualizers :maxdepth: 1 {% for id, _ in plugin.visualizers|dictsort %} - {{ id }} + {{ id.replace('_', '-') }} {% endfor %} {% else %} This plugin does not have any visualizers. diff --git a/source/theme/static/style.css b/source/theme/static/style.css index 154c7d66..a5af8d65 100644 --- a/source/theme/static/style.css +++ b/source/theme/static/style.css @@ -74,11 +74,6 @@ div.admonition.qiime1 { border: 1px solid #FAEBCC; } -/* `plugin_directory` extension */ -.action-signature th[colspan] { - text-align: center; -} - /* `tabbed` content */ .tabbed .white-bg { background-color: #FFFFFF !important;