[ENH] Some missing docstrings for bidsschematools

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.
 

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

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.
 

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,13 +305,33 @@ 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())
     return 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 = {