docstrings

Author: dwhswenson

paths_cli/compiling/_gendocs/config_handler.py

@@ -6,6 +6,17 @@
 
 
 def load_config(config_file):
+    """Load a configuration file for gendocs.
+
+    The configuration file should be YAML or JSON, and should map each
+    category name to the headings necessary to fill a DocCategoryInfo
+    instance.
+
+    Parameters
+    ----------
+    config_file : str
+        name of YAML or JSON file
+    """
     loader = select_loader(config_file)
     with open(config_file, mode='r') as f:
         dct = loader(f)

paths_cli/compiling/_gendocs/docs_generator.py

@@ -4,9 +4,9 @@
 from .config_handler import DocCategoryInfo
 
 PARAMETER_RST = """* **{p.name}**{type_str} - {p.description}{required}\n"""
-
 # TODO: add templates here instead of adding up strings in the code
 
+
 class DocsGenerator:
     """This generates the RST to describe options for compile input files.
 
@@ -19,6 +19,7 @@ class DocsGenerator:
 
     parameter_template = PARAMETER_RST
     _ANCHOR_SEP = "--"
+
     def __init__(self, config):
         self.config = config
 
@@ -37,6 +38,19 @@ def _get_cat_info(self, category_plugin):
         return cat_info
 
     def generate_category_rst(self, category_plugin, type_required=True):
+        """Generate the RST for a given category plugin.
+
+        Parameters
+        ----------
+        category_plugin : :class:`.CategoryPlugin`
+            the plugin for which we should generate the RST page
+
+        Returns
+        -------
+        str :
+            RST string for this category
+        """
+        # TODO: move type_required to DocCategoryInfo (default 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"
@@ -51,6 +65,23 @@ def generate_category_rst(self, category_plugin, type_required=True):
 
     def generate_plugin_rst(self, plugin, category_name,
                             type_required=True):
+        """Generate the RST for a given object plugin.
+
+        Parameters
+        ----------
+        plugin : class:`.InstanceCompilerPlugin`
+            the object plugin for to generate the RST for
+        category_name : str
+            the name of the category for this object
+        type_required : bool
+            whether the ``type`` parameter is required in the dict input for
+            compiling this type of object (usually category-dependent)
+
+        Returns
+        -------
+        str :
+            RST string for this object plugin
+        """
         rst_anchor = f".. _{category_name}{self._ANCHOR_SEP}{plugin.name}:"
         rst = f"{rst_anchor}\n\n{plugin.name}\n{'-' * len(plugin.name)}\n\n"
         if plugin.description:
@@ -82,12 +113,27 @@ def generate_plugin_rst(self, plugin, category_name,
         rst += "\n\n"
         return rst
 
-    def _get_filename(self, cat_info):
+    @staticmethod
+    def _get_filename(cat_info):
         fname = str(cat_info.header).lower()
         fname = fname.translate(str.maketrans(' ', '_'))
         return f"{fname}.rst"
 
     def generate(self, category_plugins, stdout=False):
+        """Generate RST output for the given plugins.
+
+        This is the main method used to generate the entire set of
+        documentation.
+
+        Parameters
+        ----------
+        category_plugin : List[:class:`.CategoryPlugin`]
+            list of category plugins document
+        stdout : bool
+            if False (default) a separate output file is generated for each
+            category plugin. If True, all text is output to stdout
+            (particularly useful for debugging/dry runs).
+        """
         for plugin in category_plugins:
             rst = self.generate_category_rst(plugin)
             if stdout:

paths_cli/compiling/_gendocs/json_type_handlers.py

@@ -1,9 +1,30 @@
 class JsonTypeHandler:
+    """Abstract class to obtain documentation type from JSON schema type.
+
+    Parameters
+    ----------
+    is_my_type : Callable[Any] -> bool
+        return True if this instance should handle the given input type
+    handler : Callable[Any] -> str
+        convert the input type to a string suitable for the RST docs
+    """
     def __init__(self, is_my_type, handler):
         self._is_my_type = is_my_type
         self.handler = handler
 
     def is_my_type(self, json_type):
+        """Determine whether this instance should handle this type.
+
+        Parameters
+        ----------
+        json_type : Any
+            input type from JSON schema
+
+        Returns
+        -------
+        bool :
+            whether to handle this type with this instance
+        """
         return self._is_my_type(json_type)
 
     def __call__(self, json_type):
@@ -21,7 +42,7 @@ def __call__(self, json_type):
 def _is_listof(json_type):
     try:
         return json_type["type"] == "array"
-    except:
+    except:  # any exception should return false (mostly Key/Type Error)
         return False
 
 
@@ -33,6 +54,18 @@ def _is_listof(json_type):
 
 
 class RefTypeHandler(JsonTypeHandler):
+    """Handle JSON types of the form {"$ref": "#/definitions/..."}
+
+    Parameters
+    ----------
+    type_name : str
+        the name to use in the RST type
+    def_string : str
+        the string following "#/definitions/" in the JSON type definition
+    link_to : str or None
+        if not None, the RST type will be linked with a ``:ref:`` pointing
+        to the anchor given by ``link_to``
+    """
     def __init__(self, type_name, def_string, link_to):
         self.type_name = type_name
         self.def_string = def_string
@@ -51,6 +84,17 @@ def _refhandler(self, json_type):
 
 
 class CategoryHandler(RefTypeHandler):
+    """Handle JSON types for OPS category definitions.
+
+    OPS category definitions show up with JSON references pointing to
+    "#/definitions/{CATEGORY}_type". This provides a convenience class over
+    the :class:RefTypeHandler to treat OPS categories.
+
+    Parameters
+    ----------
+    category : str
+        name of the category
+    """
     def __init__(self, category):
         self.category = category
         def_string = f"{category}_type"
@@ -61,6 +105,22 @@ def __init__(self, category):
 
 
 class EvalHandler(RefTypeHandler):
+    """Handle JSON types for OPS custom evaluation definitions.
+
+    Some parameters for the OPS compiler use the OPS custom evaluation
+    mechanism, which evaluates certain Python-like string input. These are
+    treated as special definition types in the JSON schema, and this object
+    provides a convenience class over :class:`.RefTypeHandler` to treat
+    custom evaluation types.
+
+    Parameters
+    ----------
+    type_name : str
+        name of the custom evaluation type
+    link_to : str or None
+        if not None, the RST type will be linked with a ``:ref:`` pointing
+        to the anchor given by ``link_to``
+    """
     def __init__(self, type_name, link_to=None):
         super().__init__(
             type_name=type_name, def_string=type_name, link_to=link_to
@@ -79,6 +139,21 @@ def __init__(self, type_name, link_to=None):
 
 
 def json_type_to_string(json_type):
+    """Convert JSON schema type to string for RST docs.
+
+    This is the primary public-facing method for dealing with JSON schema
+    types in RST document generation.
+
+    Parameters
+    ----------
+    json_type : Any
+        the type from the JSON schema
+
+    Returns
+    -------
+    str :
+        the type string description to be used in the RST document
+    """
     for handler in JSON_TYPE_HANDLERS:
         handled = handler(json_type)
         if handled != json_type:

paths_cli/compiling/gendocs.py

@@ -3,6 +3,7 @@
 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)
@@ -13,5 +14,6 @@ def main(config_file, stdout):
     generator = DocsGenerator(config)
     generator.generate(_COMPILERS.values(), stdout)
 
+
 if __name__ == "__main__":
     main()