From 444048c7af796c7e06042dc4de5d5df5b21e82b9 Mon Sep 17 00:00:00 2001
From: Anibal <anibalsolon@gmail.com>
Date: Thu, 9 Feb 2023 16:16:20 -0600
Subject: [PATCH 1/4] doc: adding docstring, fixing some syntax to agree w
 numpy

---
 tools/mkdocs_macros_bids/macros.py            | 33 +++++++++----
 .../bidsschematools/render/tables.py          | 16 +++---
 .../schemacode/bidsschematools/render/text.py | 29 ++++++++---
 .../bidsschematools/render/utils.py           | 41 ++++++++++++++--
 tools/schemacode/bidsschematools/schema.py    | 49 +++++++++++++++++--
 .../bidsschematools/types/namespace.py        | 10 ++++
 tools/schemacode/bidsschematools/validator.py |  4 +-
 7 files changed, 151 insertions(+), 31 deletions(-)

diff --git a/tools/mkdocs_macros_bids/macros.py b/tools/mkdocs_macros_bids/macros.py
index 5fe91241bb..ebdd86c1d0 100644
--- a/tools/mkdocs_macros_bids/macros.py
+++ b/tools/mkdocs_macros_bids/macros.py
@@ -72,7 +72,10 @@ def make_filename_template(dstype="raw", src_path=None, pdf_format=False, **kwar
         If False, the filename template will use HTML and include hyperlinks.
         This works on the website.
         Default is False.
-    kwargs : dict
+
+    Other Parameters
+    ----------------
+    **kwargs : dict
         Keyword arguments used to filter the schema.
         Example kwargs that may be used include: "suffixes", "datatypes",
         "extensions".
@@ -102,7 +105,13 @@ def make_entity_table(src_path=None, **kwargs):
 
     Parameters
     ----------
-    kwargs : dict
+    src_path : str or None
+        The file where this macro is called, which may be explicitly provided
+        by the "page.file.src_path" variable.
+
+    Other Parameters
+    ----------------
+    **kwargs : dict
         Keyword arguments used to filter the schema.
         Example kwargs that may be used include: "suffixes", "datatypes",
         "extensions".
@@ -125,6 +134,12 @@ def make_entity_definitions(src_path=None):
     """Generate definitions and other relevant information for entities in the
     specification.
 
+    Parameters
+    ----------
+    src_path : str or None
+        The file where this macro is called, which may be explicitly provided
+        by the "page.file.src_path" variable.
+
     Returns
     -------
     text : str
@@ -144,7 +159,7 @@ def make_glossary(src_path=None):
 
     Parameters
     ----------
-    src_path : str | None
+    src_path : str or None
         The file where this macro is called, which may be explicitly provided
         by the "page.file.src_path" variable.
 
@@ -169,7 +184,7 @@ def make_suffix_table(suffixes, src_path=None):
     ----------
     suffixes : list of str
         A list of the suffixes to include in the table.
-    src_path : str | None
+    src_path : str or None
         The file where this macro is called, which may be explicitly provided
         by the "page.file.src_path" variable.
 
@@ -199,7 +214,7 @@ def make_metadata_table(field_info, src_path=None):
         Until requirement levels can be codified in the schema,
         this argument will be dictionary, with the field names as keys and
         the requirement levels as values.
-    src_path : str | None
+    src_path : str or None
         The file where this macro is called, which may be explicitly provided
         by the "page.file.src_path" variable.
 
@@ -224,7 +239,7 @@ def make_sidecar_table(table_name, src_path=None):
     ----------
     table_name : str or list of str
         Qualified name(s) in schema.rules.sidecars
-    src_path : str | None
+    src_path : str or None
         The file where this macro is called, which may be explicitly provided
         by the "page.file.src_path" variable.
 
@@ -249,7 +264,7 @@ def make_subobject_table(object_name, src_path=None):
     ----------
     object_tuple : tuple of string
         A tuple pointing to the object to render.
-    src_path : str | None
+    src_path : str or None
         The file where this macro is called, which may be explicitly provided
         by the "page.file.src_path" variable.
 
@@ -283,7 +298,7 @@ def make_columns_table(table_name, src_path=None):
         Until requirement levels can be codified in the schema,
         this argument will be a dictionary, with the column names as keys and
         the requirement levels as values.
-    src_path : str | None
+    src_path : str or None
         The file where this macro is called, which may be explicitly provided
         by the "page.file.src_path" variable.
 
@@ -325,7 +340,7 @@ def define_common_principles(src_path=None):
 
     Parameters
     ----------
-    src_path : str | None
+    src_path : str or None
         The file where this macro is called, which may be explicitly provided
         by the "page.file.src_path" variable.
 
diff --git a/tools/schemacode/bidsschematools/render/tables.py b/tools/schemacode/bidsschematools/render/tables.py
index 8a3f15090e..772636ea1a 100644
--- a/tools/schemacode/bidsschematools/render/tables.py
+++ b/tools/schemacode/bidsschematools/render/tables.py
@@ -44,7 +44,7 @@ def _make_object_table(
         information to be added to the object's description).
     table_type : str
         The name of the field type. For example, "metadata".
-    src_path : str | None
+    src_path : str or None
         The file where this macro is called, which may be explicitly provided
         by the "page.file.src_path" variable.
     tablefmt : string, optional
@@ -153,7 +153,7 @@ def _make_table_from_rule(
         Qualified name(s) in schema.rules.tabular_data (for "columns" tables) or
         schema.rules.sidecars (for "metadata" files).
         Only one item may be provided for columns tables.
-    src_path : str | None
+    src_path : str or None
         The file where this macro is called, which may be explicitly provided
         by the "page.file.src_path" variable.
     tablefmt : string, optional
@@ -285,7 +285,7 @@ def make_entity_table(schema, tablefmt="github", src_path=None, **kwargs):
         Directory containing schema, which is stored in yaml files.
     tablefmt : string, optional
         The target table format. The default is "github" (GitHub format).
-    src_path : str | None
+    src_path : str or None
         The file where this macro is called, which may be explicitly provided
         by the "page.file.src_path" variable.
 
@@ -356,7 +356,7 @@ def make_suffix_table(schema, suffixes, src_path=None, tablefmt="github"):
     ----------
     schema : dict
     suffixes : list of str
-    src_path : str | None
+    src_path : str or None
         The file where this macro is called, which may be explicitly provided
         by the "page.file.src_path" variable.
     tablefmt : str
@@ -418,7 +418,7 @@ def make_sidecar_table(
         The BIDS schema.
     table_name : str or list of str
         Qualified name(s) in schema.rules.sidecars
-    src_path : str | None
+    src_path : str or None
         The file where this macro is called, which may be explicitly provided
         by the "page.file.src_path" variable.
     tablefmt : string, optional
@@ -456,7 +456,7 @@ def make_metadata_table(schema, field_info, src_path=None, tablefmt="github"):
         and the second string is additional table-specific information
         about the metadata field that will be appended to the field's base
         definition from the schema.
-    src_path : str | None
+    src_path : str or None
         The file where this macro is called, which may be explicitly provided
         by the "page.file.src_path" variable.
     tablefmt : string, optional
@@ -513,7 +513,7 @@ def make_subobject_table(
         The BIDS schema.
     object_name : str
         Qualified name in schema.objects
-    src_path : str | None
+    src_path : str or None
         The file where this macro is called, which may be explicitly provided
         by the "page.file.src_path" variable.
     tablefmt : string, optional
@@ -565,7 +565,7 @@ def make_columns_table(
     table_name : str
         Qualified name in schema.rules.tabular_data.
         Only one table may be provided in this function.
-    src_path : str | None
+    src_path : str or None
         The file where this macro is called, which may be explicitly provided
         by the "page.file.src_path" variable.
     tablefmt : string, optional
diff --git a/tools/schemacode/bidsschematools/render/text.py b/tools/schemacode/bidsschematools/render/text.py
index 81a3c8d910..93c1a38300 100644
--- a/tools/schemacode/bidsschematools/render/text.py
+++ b/tools/schemacode/bidsschematools/render/text.py
@@ -88,7 +88,7 @@ def make_glossary(schema, src_path=None):
     schema : dict
         The schema object, which is a dictionary with nested dictionaries and
         lists stored within it.
-    src_path : str | None
+    src_path : str or None
         The file where this macro is called, which may be explicitly provided
         by the "page.file.src_path" variable.
 
@@ -229,7 +229,7 @@ def make_filename_template(
     schema : dict
         The schema object, which is a dictionary with nested dictionaries and
         lists stored within it.
-    src_path : str | None
+    src_path : str or None
         The file where this macro is called, which may be explicitly provided
         by the "page.file.src_path" variable.
     n_dupes_to_combine : int
@@ -241,7 +241,10 @@ def make_filename_template(
         If False, the filename template will use HTML and include hyperlinks.
         This works on the website.
         Default is False.
-    kwargs : dict
+
+    Other Parameters
+    ----------------
+    **kwargs : dict
         Keyword arguments used to filter the schema.
         Example kwargs that may be used include: "suffixes", "datatypes",
         "extensions".
@@ -410,7 +413,21 @@ def make_filename_template(
 
 
 def append_filename_template_legend(text, pdf_format=False):
-    """Append a legend to filename templates."""
+    """Append a legend to filename templates.
+
+    Parameters
+    ----------
+    text : str
+        The text to append the legend to.
+
+    pdf_format : bool
+        Whether to format the legend for PDF output.
+
+    Returns
+    -------
+    str :
+        The text with the legend appended.
+    """
     if pdf_format:
         info_str = ""
     else:
@@ -456,7 +473,7 @@ def define_common_principles(schema, src_path=None):
     ----------
     schema : dict
         The BIDS schema.
-    src_path : str | None
+    src_path : str or None
         The file where this macro is called, which may be explicitly provided
         by the "page.file.src_path" variable.
 
@@ -489,7 +506,7 @@ def define_allowed_top_directories(schema, src_path=None) -> str:
     ----------
     schema : dict
         The BIDS schema.
-    src_path : str | None
+    src_path : str or None
         The file where this macro is called, which may be explicitly provided
         by the "page.file.src_path" variable.
 
diff --git a/tools/schemacode/bidsschematools/render/utils.py b/tools/schemacode/bidsschematools/render/utils.py
index 1dbddbff9b..9764a4efbe 100644
--- a/tools/schemacode/bidsschematools/render/utils.py
+++ b/tools/schemacode/bidsschematools/render/utils.py
@@ -159,6 +159,18 @@ def flatten_multiindexed_columns(df):
 
 
 def get_link(string):
+    """Return a hyperlink to the JSON specification for a given JSON type.
+
+    Parameters
+    ----------
+    string : str
+        The JSON type to link to.
+
+    Returns
+    -------
+    url : str
+        The hyperlink to the JSON specification for the given JSON type.
+    """
     refs = {
         "array": "https://www.w3schools.com/js/js_json_arrays.asp",
         "string": "https://www.w3schools.com/js/js_json_datatypes.asp",
@@ -185,7 +197,7 @@ def resolve_metadata_type(definition):
 
     Returns
     -------
-    string : :obj:`str`
+    string : str
         A string describing the valid value types for the metadata term.
     """
     if "type" in definition.keys():
@@ -230,8 +242,7 @@ def describe_valid_values(definition):
 
     Returns
     -------
-    :obj:`str`
-        A sentence describing valid values for the object.
+    str : A sentence describing valid values for the object.
     """
     description = ""
     if "anyOf" in definition.keys():
@@ -294,6 +305,16 @@ def get_relpath(src_path):
 
 
 def normalize_requirements(text):
+    """Normalize requirements wording in a string.
+
+    Parameters
+    ----------
+    text : str
+
+    Returns
+    -------
+    text : str
+    """
     for level in ("optional", "recommended", "required", "deprecated"):
         # Replace both "optional" and "Optional" with "OPTIONAL"
         text = text.replace(level.title(), level).replace(level, level.upper())
@@ -301,6 +322,16 @@ def normalize_requirements(text):
 
 
 def normalize_breaks(text):
+    """Normalize line breaks in a string, for new lines, escaped new lines and double new lines.
+
+    Parameters
+    ----------
+    text : str
+
+    Returns
+    -------
+    text : str
+    """
     # A backslash before a newline means continue a string
     text = text.replace("\\\n", "")
     # Two newlines should be respected
@@ -320,6 +351,10 @@ def num2words(integer, to="ordinal"):
     ----------
     integer : int
     to : {"ordinal", "cardinal"}, optional
+
+    Returns
+    -------
+    word : str
     """
     if to == "ordinal":
         mapper = {
diff --git a/tools/schemacode/bidsschematools/schema.py b/tools/schemacode/bidsschematools/schema.py
index 57dd3ce956..670d8417a9 100644
--- a/tools/schemacode/bidsschematools/schema.py
+++ b/tools/schemacode/bidsschematools/schema.py
@@ -67,7 +67,21 @@ def _find(obj, predicate):
 
 
 def dereference(namespace, inplace=True):
-    """Replace references in namespace with the contents of the referred object"""
+    """Replace references in namespace with the contents of the referred object
+
+    Parameters
+    ----------
+    namespace : Namespace
+        Namespace for which to dereference
+
+    inplace : bool, optional
+        Whether to modify the namespace in place or create a copy, by default True
+
+    Returns
+    -------
+    namespace : Namespace
+        Deferred namespace
+    """
     if not inplace:
         namespace = deepcopy(namespace)
     for struct in _find(namespace, lambda obj: "$ref" in obj):
@@ -77,7 +91,17 @@ def dereference(namespace, inplace=True):
 
 
 def flatten_enums(namespace, inplace=True):
-    """Replace enum collections with a single enum
+    """Replace enum collections with a single enum.
+
+    Parameters
+    ----------
+    schema : dict
+        Schema in dictionary form to be flattened.
+
+    Returns
+    -------
+    schema : dict
+        Schema with flattened enums.
 
     >>> struct = {
     ...   "anyOf": [
@@ -121,6 +145,10 @@ def load_schema(schema_path=None):
     -------
     dict
         Schema in dictionary form.
+
+    Notes
+    -----
+    This function is cached, so it will only be called once per schema path.
     """
     if schema_path is None:
         schema_path = utils.get_schema_path()
@@ -137,6 +165,18 @@ def load_schema(schema_path=None):
 
 
 def export_schema(schema):
+    """Export the schema to JSON format.
+
+    Parameters
+    ----------
+    schema : dict
+        The schema object, in dictionary form.
+
+    Returns
+    -------
+    json : str
+        The schema serialized as a JSON string.
+    """
     versioned = Namespace.build({"schema_version": __version__, "bids_version": __bids_version__})
     versioned.update(schema)
     return versioned.to_json()
@@ -150,7 +190,10 @@ def filter_schema(schema, **kwargs):
     schema : dict
         The schema object, which is a dictionary with nested dictionaries and
         lists stored within it.
-    kwargs : dict
+
+    Other Parameters
+    ----------------
+    **kwargs : dict
         Keyword arguments used to filter the schema.
         Example kwargs that may be used include: "suffixes", "datatypes",
         "extensions".
diff --git a/tools/schemacode/bidsschematools/types/namespace.py b/tools/schemacode/bidsschematools/types/namespace.py
index c637a44cd3..828e77ea42 100644
--- a/tools/schemacode/bidsschematools/types/namespace.py
+++ b/tools/schemacode/bidsschematools/types/namespace.py
@@ -19,6 +19,16 @@ def _expand_dots(entry: ty.Tuple[str, ty.Any]) -> ty.Tuple[str, ty.Any]:
 def expand(element):
     """Expand a dict, recursively, to replace dots in keys with recursive dictionaries
 
+    Parameters
+    ----------
+    element : dict
+        The dictionary to expand
+
+    Returns
+    -------
+    dict :
+        The expanded dictionary
+
     Examples
     --------
     >>> expand({"a": 1, "b.c": 2, "d": [{"e": 3, "f.g": 4}]})
diff --git a/tools/schemacode/bidsschematools/validator.py b/tools/schemacode/bidsschematools/validator.py
index 5eba1c730a..66776d155f 100644
--- a/tools/schemacode/bidsschematools/validator.py
+++ b/tools/schemacode/bidsschematools/validator.py
@@ -514,7 +514,7 @@ def select_schema_dir(
         according to the respective schema version, e.g. "1.7.0".
         If the path starts with the string "{module_path}" it will be expanded relative to the
         module path.
-    schema_version : str or None
+    schema_version : str | None
         Version of BIDS schema, or path to schema.
         If a path is given, this will be expanded and used directly, not concatenated with
         `schema_reference_root`.
@@ -691,7 +691,7 @@ def validate_bids(
         according to the respective schema version, e.g. "1.7.0".
         If the path starts with the string "{module_path}" it will be expanded relative to the
         module path.
-    schema_version : str or None, optional
+    schema_version : str | None, optional
         Version of BIDS schema, or path to schema.
         If a path is given, this will be expanded and used directly, not concatenated with
         `schema_reference_root`.

From 1c840236da4a797291c8ad31a614e21e3ecf86c3 Mon Sep 17 00:00:00 2001
From: Anibal <anibalsolon@gmail.com>
Date: Thu, 9 Feb 2023 22:47:55 -0600
Subject: [PATCH 2/4] chore: cleaning up unused function

---
 tools/schemacode/bidsschematools/schema.py | 7 -------
 1 file changed, 7 deletions(-)

diff --git a/tools/schemacode/bidsschematools/schema.py b/tools/schemacode/bidsschematools/schema.py
index 670d8417a9..18026a9a17 100644
--- a/tools/schemacode/bidsschematools/schema.py
+++ b/tools/schemacode/bidsschematools/schema.py
@@ -19,13 +19,6 @@ class BIDSSchemaError(Exception):
     """Errors indicating invalid values in the schema itself"""
 
 
-def _get_entry_name(path):
-    if path.suffix == ".yaml":
-        return path.name[:-5]  # no .yaml
-    else:
-        return path.name
-
-
 def _get_bids_version(bids_schema_dir):
     """Determine schema version, with directory name, file specification, and string fallback."""
 

From 8eed135bd74d54dfb7cb618a572a92aa809c32b3 Mon Sep 17 00:00:00 2001
From: Anibal <anibalsolon@gmail.com>
Date: Fri, 10 Feb 2023 10:17:22 -0600
Subject: [PATCH 3/4] doc: stating some implicit info

---
 tools/schemacode/bidsschematools/schema.py | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/tools/schemacode/bidsschematools/schema.py b/tools/schemacode/bidsschematools/schema.py
index 18026a9a17..96fb6d8b0f 100644
--- a/tools/schemacode/bidsschematools/schema.py
+++ b/tools/schemacode/bidsschematools/schema.py
@@ -84,7 +84,10 @@ def dereference(namespace, inplace=True):
 
 
 def flatten_enums(namespace, inplace=True):
-    """Replace enum collections with a single enum.
+    """Replace enum collections with a single enum, merging enums contents.
+
+    The function helps reducing the complexity of the schema by assuming
+    that the values in the conditions (anyOf) are mutually exclusive.
 
     Parameters
     ----------

From a7e7058afa4c901001816894c02642cc6273ab2d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Anibal=20S=C3=B3lon?= <anibalsolon@gmail.com>
Date: Thu, 16 Feb 2023 19:37:08 -0600
Subject: [PATCH 4/4] fix: missing ors

---
 tools/schemacode/bidsschematools/validator.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/tools/schemacode/bidsschematools/validator.py b/tools/schemacode/bidsschematools/validator.py
index 66776d155f..5eba1c730a 100644
--- a/tools/schemacode/bidsschematools/validator.py
+++ b/tools/schemacode/bidsschematools/validator.py
@@ -514,7 +514,7 @@ def select_schema_dir(
         according to the respective schema version, e.g. "1.7.0".
         If the path starts with the string "{module_path}" it will be expanded relative to the
         module path.
-    schema_version : str | None
+    schema_version : str or None
         Version of BIDS schema, or path to schema.
         If a path is given, this will be expanded and used directly, not concatenated with
         `schema_reference_root`.
@@ -691,7 +691,7 @@ def validate_bids(
         according to the respective schema version, e.g. "1.7.0".
         If the path starts with the string "{module_path}" it will be expanded relative to the
         module path.
-    schema_version : str | None, optional
+    schema_version : str or None, optional
         Version of BIDS schema, or path to schema.
         If a path is given, this will be expanded and used directly, not concatenated with
         `schema_reference_root`.