roughly working automatic compile docs generation

Author: dwhswenson

paths_cli/compiling/_gendocs/README.md

@@ -0,0 +1,6 @@
+# _docgen
+
+Tools for generating documentation for the tools import `paths_cli.compiling`.
+Note that this entire directory is considered outside the API, so nothing in
+here should be strongly relied on.
+

paths_cli/compiling/_gendocs/__init__.py

@@ -0,0 +1,2 @@
+from .config_handler import load_config, DocCategoryInfo
+from .docs_generator import DocsGenerator

paths_cli/compiling/_gendocs/config_handler.py

@@ -0,0 +1,15 @@
+from collections import namedtuple
+from paths_cli.commands.compile import select_loader
+
+DocCategoryInfo = namedtuple('DocCategoryInfo', ['header', 'description'],
+                             defaults=[None])
+
+
+def load_config(config_file):
+    loader = select_loader(config_file)
+    with open(config_file, mode='r') as f:
+        dct = loader(f)
+
+    result = {category: DocCategoryInfo(**details)
+              for category, details in dct.items()}
+    return result

paths_cli/compiling/_gendocs/docs_generator.py

@@ -0,0 +1,91 @@
+import sys
+from paths_cli.compiling.core import Parameter
+from .json_type_handlers import json_type_to_string
+from .config_handler import DocCategoryInfo
+
+PARAMETER_RST = """* **{p.name}**{type_str} - {p.description}{required}\n"""
+
+
+class DocsGenerator:
+    """This generates the RST to describe options for compile input files.
+    """
+
+    parameter_template = PARAMETER_RST
+    _ANCHOR_SEP = "--"
+    def __init__(self, config):
+        self.config = config
+
+    def format_parameter(self, parameter, type_str=None):
+        required = " (required)" if parameter.required else ""
+        return self.parameter_template.format(
+            p=parameter, type_str=type_str, required=required
+        )
+
+    def _get_cat_info(self, category_plugin):
+        cat_info = self.config.get(category_plugin.label, None)
+        if cat_info is None:
+            cat_info = DocCategoryInfo(category_plugin.label)
+        return cat_info
+
+    def generate_category_rst(self, category_plugin, type_required=True):
+        cat_info = self._get_cat_info(category_plugin)
+        rst = f".. _compiling--{category_plugin.label}:\n\n"
+        rst += f"{cat_info.header}\n{'=' * len(str(cat_info.header))}\n\n"
+        if cat_info.description:
+            rst += cat_info.description + "\n\n"
+        rst += ".. contents:: :local:\n\n"
+        for obj in category_plugin.type_dispatch.values():
+            rst += self.generate_plugin_rst(
+                obj, category_plugin.label, type_required
+            )
+        return rst
+
+    def generate_plugin_rst(self, plugin, strategy_name,
+                            type_required=True):
+        rst_anchor = f".. _{strategy_name}{self._ANCHOR_SEP}{plugin.name}:"
+        rst = f"{rst_anchor}\n\n{plugin.name}\n{'-' * len(plugin.name)}\n\n"
+        if plugin.description:
+            rst += plugin.description + "\n\n"
+        if type_required:
+            type_param = Parameter(
+                "type",
+                json_type="",
+                loader=None,
+                description=(f"type identifier; must exactly match the "
+                             f"string ``{plugin.name}``"),
+            )
+            rst += self.format_parameter(
+                type_param, type_str=""
+            )
+
+        name_param = Parameter(
+            "name",
+            json_type="string",
+            loader=None,
+            default="",
+            description="name this object in order to reuse it",
+        )
+        rst += self.format_parameter(name_param, type_str=" (*string*)")
+        for param in plugin.parameters:
+            type_str = f" ({json_type_to_string(param.json_type)})"
+            rst += self.format_parameter(param, type_str)
+
+        rst += "\n\n"
+        return rst
+
+    def _get_filename(self, cat_info):
+        fname = str(cat_info.header).lower()
+        fname = fname.translate(str.maketrans(' ', '_'))
+        return f"{fname}.rst"
+
+    def generate(self, category_plugins, stdout=False):
+        for plugin in category_plugins:
+            rst = self.generate_category_rst(plugin)
+            if stdout:
+                sys.stdout.write(rst)
+                sys.stdout.flush()
+            else:
+                cat_info = self._get_cat_info(plugin)
+                filename = self._get_filename(cat_info)
+                with open(filename, 'w') as f:
+                    f.write(rst)

paths_cli/compiling/_gendocs/json_type_handlers.py

@@ -0,0 +1,86 @@
+class JsonTypeHandler:
+    def __init__(self, is_my_type, handler):
+        self._is_my_type = is_my_type
+        self.handler = handler
+
+    def is_my_type(self, json_type):
+        return self._is_my_type(json_type)
+
+    def __call__(self, json_type):
+        if self.is_my_type(json_type):
+            return self.handler(json_type)
+        return json_type
+
+
+handle_object = JsonTypeHandler(
+    is_my_type=lambda json_type: json_type == "object",
+    handler=lambda json_type: "dict",
+)
+
+
+def _is_listof(json_type):
+    try:
+        return json_type["type"] == "array"
+    except:
+        return False
+
+
+handle_listof = JsonTypeHandler(
+    is_my_type=_is_listof,
+    handler=lambda json_type: "list of "
+    + json_type_to_string(json_type["items"]),
+)
+
+
+class RefTypeHandler(JsonTypeHandler):
+    def __init__(self, type_name, def_string, link_to):
+        self.type_name = type_name
+        self.def_string = def_string
+        self.link_to = link_to
+        self.json_check = {"$ref": "#/definitions/" + def_string}
+        super().__init__(is_my_type=self._reftype, handler=self._refhandler)
+
+    def _reftype(self, json_type):
+        return json_type == self.json_check
+
+    def _refhandler(self, json_type):
+        rst = f"{self.type_name}"
+        if self.link_to:
+            rst = f":ref:`{rst} <{self.link_to}>`"
+        return rst
+
+
+class CategoryHandler(RefTypeHandler):
+    def __init__(self, category):
+        self.category = category
+        def_string = f"{category}_type"
+        link_to = f"compiling--{category}"
+        super().__init__(
+            type_name=category, def_string=def_string, link_to=link_to
+        )
+
+
+class EvalHandler(RefTypeHandler):
+    def __init__(self, type_name, link_to=None):
+        super().__init__(
+            type_name=type_name, def_string=type_name, link_to=link_to
+        )
+
+
+JSON_TYPE_HANDLERS = [
+    handle_object,
+    handle_listof,
+    CategoryHandler("engine"),
+    CategoryHandler("cv"),
+    CategoryHandler("volume"),
+    EvalHandler("EvalInt"),
+    EvalHandler("EvalFloat"),
+]
+
+
+def json_type_to_string(json_type):
+    for handler in JSON_TYPE_HANDLERS:
+        handled = handler(json_type)
+        if handled != json_type:
+            return handled
+    return json_type

paths_cli/compiling/core.py

@@ -143,17 +143,21 @@ class InstanceCompilerPlugin(OPSPlugin):
         Name used in the text input for this object.
     aliases : List[str]
         Other names that can be used.
+    description : str
+        String description used in the documentation
     requires_ops : Tuple[int, int]
         version of OpenPathSampling required for this functionality
     requires_cli : Tuple[int, int]
         version of the OPS CLI requires for this functionality
     """
     SCHEMA = "http://openpathsampling.org/schemas/sim-setup/draft01.json"
     category = None
-    def __init__(self, builder, parameters, name=None, aliases=None,
-                 requires_ops=(1, 0), requires_cli=(0, 3)):
+    def __init__(self, builder, parameters, name=None, *, aliases=None,
+                 description=None, requires_ops=(1, 0),
+                 requires_cli=(0, 3)):
         super().__init__(requires_ops, requires_cli)
         self.aliases = aliases
+        self.description = description
         self.attribute_table = {p.name: p.loader for p in parameters
                                 if p.required}
         self.optional_attributes = {p.name: p.loader for p in parameters

paths_cli/compiling/engines.py

@@ -43,6 +43,7 @@ def _openmm_options(dct):
                     remapper=_openmm_options),
     parameters=OPENMM_PARAMETERS,
     name='openmm',
+    description="Use OpenMM for the dynamics.",
 )
 
 ENGINE_COMPILER = CategoryPlugin(EngineCompilerPlugin, aliases=['engines'])

paths_cli/compiling/gendocs.py

@@ -0,0 +1,16 @@
+import click
+from paths_cli.compiling._gendocs import DocsGenerator, load_config
+from paths_cli.compiling.root_compiler import _COMPILERS
+from paths_cli.commands.compile import register_installed_plugins
+
+@click.command()
+@click.argument("config_file")
+@click.option("--stdout", type=bool, is_flag=True, default=False)
+def main(config_file, stdout):  # -no-cov-
+    register_installed_plugins()
+    config = load_config(config_file)
+    generator = DocsGenerator(config)
+    generator.generate(_COMPILERS.values(), stdout)
+
+if __name__ == "__main__":
+    main()

paths_cli/compiling/shooting.py

@@ -32,5 +32,5 @@ def _remapping_gaussian_stddev(dct):
         'uniform': build_uniform_selector,
         'gaussian': build_gaussian_selector,
     },
-    label='shooting selectors'
+    label='shooting-selectors'
 )

paths_cli/compiling/strategies.py

@@ -4,6 +4,7 @@
     StrategyCompilerPlugin, CategoryPlugin
 )
 from paths_cli.compiling.root_compiler import compiler_for
+from paths_cli.compiling.json_type import json_type_ref
 
 def _strategy_name(class_name):
     return f"openpathsampling.strategies.{class_name}"
@@ -16,9 +17,10 @@ def _group_parameter(group_name):
 SP_SELECTOR_PARAMETER = Parameter('selector', shooting_selector_compiler,
                                   default=None)
 
-ENGINE_PARAMETER = Parameter('engine', compiler_for('engine'),
-                             description="the engine for moves of this "
-                             "type")
+ENGINE_PARAMETER = Parameter(
+    'engine', compiler_for('engine'), json_type=json_type_ref('engine'),
+    description="the engine for moves of this type"
+)
 
 SHOOTING_GROUP_PARAMETER = _group_parameter('shooting')
 REPEX_GROUP_PARAMETER = _group_parameter('repex')
@@ -57,7 +59,7 @@ def _group_parameter(group_name):
         REPEX_GROUP_PARAMETER,
         REPLACE_TRUE_PARAMETER
     ],
-    name='nearest-neighbor=repex',
+    name='nearest-neighbor-repex',
 )
 
 build_all_set_repex_strategy = StrategyCompilerPlugin(