Merge pull request #817 from IanCa/dev_docs

Add linkchecker to documentation, and misc minor fixes to doc strings/templates

docs/source/_templates/custom-class-template.rst

@@ -8,34 +8,24 @@
 .. rubric:: {{ _('Methods') }}
 
 .. autosummary::
-{% for item in methods %}
-   {{ module }}.{{ objname }}.{{ item }}
+{%- for item in methods %}
+   {{ objname }}.{{ item }}
 {%- endfor %}
 
 .. rubric:: {{ _('Attributes') }}
 
 .. autosummary::
-{% for item in attributes %}
-   {{ module }}.{{ objname }}.{{ item }}
+{%- for item in attributes %}
+   {{ objname }}.{{ item }}
 {%- endfor %}
 
-.. toctree::
-   :hidden:
-
-{% for item in methods %}
-   {{ fullname }}#method-{{ item }}
-{%- endfor %}
-{% for item in attributes %}
-   {{ fullname }}#attribute-{{ item }}
-{%- endfor %}
-
-{% for item in methods %}
+{%- for item in methods %}
 .. _method-{{ item }}:
 
 .. automethod:: {{ module }}.{{ objname }}.{{ item }}
 {%- endfor %}
 
-{% for item in attributes %}
+{%- for item in attributes %}
 .. _attribute-{{ item }}:
 
 .. autoattribute:: {{ module }}.{{ objname }}.{{ item }}

docs/source/_templates/custom-module-template.rst

@@ -38,7 +38,7 @@
    .. rubric:: {{ _('Classes') }}
 
    .. autosummary::
-      :toctree:
+      :toctree: _generated_classes
       :template: custom-class-template.rst
    {% for item in classes %}
       {{ item }}

docs/source/conf.py

@@ -39,7 +39,7 @@
     "myst_parser",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
-    "sphinx.ext.autosectionlabel",
+    # "sphinx.ext.autosectionlabel",
     "sphinx.ext.intersphinx",
     "sphinx.ext.coverage",
     "sphinx.ext.mathjax",

hed/models/definition_dict.py

@@ -30,12 +30,14 @@ def __init__(self, def_dicts=None, hed_schema=None):
             self.add_definitions(def_dicts, hed_schema)
 
     def add_definitions(self, def_dicts, hed_schema=None):
-        """ Add definitions from dict(s) to this dict.
+        """ Add definitions from dict(s) or strings(s) to this dict.
 
         Parameters:
-            def_dicts (list, DefinitionDict, or dict): DefinitionDict or list of DefinitionDicts/strings/dicts whose
-                                                definitions should be added.
-                                        Note dict form expects DefinitionEntries in the same form as a DefinitionDict
+            def_dicts (list, DefinitionDict, dict, or str): DefinitionDict or list of DefinitionDicts/strings/dicts whose
+                definitions should be added.
+                Note - dict form expects DefinitionEntries in the same form as a DefinitionDict
+                Note - str or list of strings will parse the strings using the hed_schema.
+                Note - You can mix and match types, eg [DefinitionDict, str, list of str] would be valid input.
             hed_schema(HedSchema or None): Required if passing strings or lists of strings, unused otherwise.
 
         :raises TypeError:

hed/models/expression_parser.py

@@ -332,7 +332,7 @@ def __init__(self, expression_string):
 
         '"Event"' - Finds the Event tag, but not any descendent tags
 
-        'Def/DefName/*' - Find Def/DefName instances with placeholders, regardless of the value of the placeholder
+        `Def/DefName/*` - Find Def/DefName instances with placeholders, regardless of the value of the placeholder
 
         'Eve*' - Find any short tags that begin with Eve*, such as Event, but not Sensory-event
 

hed/models/hed_tag.py

@@ -499,6 +499,7 @@ def default_unit(self):
         """ Get the default unit class unit for this tag.
 
             Only a tag with a single unit class can have default units.
+
         Returns:
             unit(UnitEntry or None): the default unit entry for this tag, or None
         """

hed/schema/hed_schema_io.py

@@ -223,7 +223,7 @@ def load_schema_version(xml_version=None, xml_folder=None):
                                            An empty string returns the latest version
                                            A json str format is also supported,
                                            based on the output of HedSchema.get_formatted_version
-                                           Basic format: '[schema_namespace:][library_name_][X.Y.Z]'.
+                                           Basic format: `[schema_namespace:][library_name_][X.Y.Z]`.
         xml_folder (str): Path to a folder containing schema.
 
     Returns:

hed/schema/schema_attribute_validators.py

@@ -1,13 +1,15 @@
 """The built-in functions to validate known attributes.
 
 Template for the functions:
-attribute_checker_template(hed_schema, tag_entry, attribute_name, possible_values):
-    hed_schema (HedSchema): The schema to use for validation
-    tag_entry (HedSchemaEntry): The schema entry for this tag.
-    attribute_name (str): The name of this attribute
+
+- ``attribute_checker_template(hed_schema, tag_entry, attribute_name)``:
+  - ``hed_schema (HedSchema)``: The schema to use for validation.
+  - ``tag_entry (HedSchemaEntry)``: The schema entry for this tag.
+  - ``attribute_name (str)``: The name of this attribute.
+
 Returns:
-    bool
-"""
+    - ``bool``: Description of the return value.
+    """
 
 from hed.errors.error_types import SchemaWarnings, ValidationErrors, SchemaAttributeErrors
 from hed.errors.error_reporter import ErrorHandler

hed/schema/schema_compare.py

@@ -176,14 +176,14 @@ def compare_schemas(schema1, schema2, attribute_filter=HedKey.InLibrary, section
         schema1 (HedSchema): The first schema to be compared.
         schema2 (HedSchema): The second schema to be compared.
         attribute_filter (str, optional): The attribute to filter entries by.
-                                        Entries without this attribute are skipped.
-                                        The most common use would be HedKey.InLibrary
-                                        If it evaluates to False, no filtering is performed.
+            Entries without this attribute are skipped.
+            The most common use would be HedKey.InLibrary
+            If it evaluates to False, no filtering is performed.
         sections(list): the list of sections to compare.  By default, just the tags section.
-                        If None, checks all sections including header, prologue, and epilogue.
+            If None, checks all sections including header, prologue, and epilogue.
 
     Returns:
-    tuple: A tuple containing four dictionaries:
+        tuple: A tuple containing four dictionaries:
         - matches(dict): Entries present in both schemas and are equal.
         - not_in_schema1(dict): Entries present in schema2 but not in schema1.
         - not_in_schema2(dict): Entries present in schema1 but not in schema2.

hed/tools/analysis/hed_type_defs.py

@@ -11,7 +11,7 @@ class HedTypeDefs:
         def_map (dict):  keys are definition names, values are dict {type_values, description, tags}
                          Example: A definition 'famous-face-cond' with contents
                          `(Condition-variable/Face-type,Description/A face that should be recognized by the
-                                                   participants,(Image,(Face,Famous)))`
+                         participants,(Image,(Face,Famous)))`
                          would have type_values ['face_type'].  All items are strings not objects.
 
 

hed/tools/remodeling/backup_manager.py

@@ -224,7 +224,7 @@ def get_task(task_names, file_path):
         """ Return the task if the file name contains a task_xxx where xxx is in task_names.
 
         Parameters:
-            task_names (list):  List of task names (without the task_ prefix).
+            task_names (list):  List of task names (without the `task_` prefix).
             file_path (str):    Path of the filename to be tested.
 
         Returns:

hed/validator/tag_util/group_util.py

@@ -71,6 +71,7 @@ def check_tag_level_issue(original_tag_list, is_top_level, is_group):
         """ Report tags incorrectly positioned in hierarchy.
 
             Top-level groups can contain definitions, Onset, etc. tags.
+
         Parameters:
             original_tag_list (list): HedTags containing the original tags.
             is_top_level (bool): If True, this group is a "top level tag group"

readthedocs.yml

@@ -8,14 +8,16 @@ build:
   os: "ubuntu-22.04"
   tools:
     python: "3.7"
+  jobs:
+    pre_build:
+      - sphinx-build -W --keep-going -q -b linkcheck -d docs/_build/doctrees docs/source/ docs/_build/linkcheck
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
   builder: html
   configuration: docs/source/conf.py
   fail_on_warning: false
 
-
 python:
   install:
    - requirements: docs/requirements.txt