[ENH] Add macro to render descriptions (#1495)

Author: Remi-Gau

macros_doc.md

@@ -92,6 +92,7 @@ All the macros we use are in listed in this
 | make_suffix_table              | Generate a markdown table of suffix information.                                       | Yes         | [link](https://github.com/bids-standard/bids-specification/blob/9201b203ffaa72d83b2fa30d1c61f46f089f77de/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md?plain=1#L199) |
 | define_common_principles       | List the common principles and definitions.                                            | Yes         | [link](https://github.com/bids-standard/bids-specification/blob/831ee55577b91aaa110153e9269e7829b095fb6f/src/02-common-principles.md?plain=1#L12)                                           |
 | define_allowed_top_directories | Create a list of allowed top-level directories with their descriptions.                | Yes         | [link](https://github.com/bids-standard/bids-specification/blob/2a701fd034d51c25e8fe18ba67bb7b76621ba477/src/02-common-principles.md?plain=1#L124)                                          |
+| render_description             | Renders the description of an object in the schema.                                    | Yes         | [link] (???)                                          |
 
 
 ## When should I use a macro?

src/modality-agnostic-files.md

@@ -11,7 +11,12 @@ Templates:
 
 ### `dataset_description.json`
 
-The file `dataset_description.json` is a JSON file describing the dataset.
+<!-- This block generates a description.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___render_text("objects.files.dataset_description.description") }}
+
 Every dataset MUST include this file with the following fields:
 
 <!-- This block generates a metadata table.
@@ -156,27 +161,19 @@ Example:
 
 ### `README`
 
-A REQUIRED text file, `README`, SHOULD describe the dataset in more detail.
-The `README` file MUST be either in ASCII or UTF-8 encoding and MAY have one of the extensions:
-`.md` ([Markdown](https://www.markdownguide.org/)),
-`.rst` ([reStructuredText](https://docutils.sourceforge.io/rst.html)),
-or `.txt`.
-A BIDS dataset MUST NOT contain more than one `README` file (with or without extension)
-at its root directory.
-BIDS does not make any recommendations with regards to the
-[Markdown flavor](https://www.markdownguide.org/extended-syntax/#lightweight-markup-languages)
-and does not validate the syntax of Markdown and reStructuredText.
-The `README` file SHOULD be structured such that its contents can be easily understood
-even if the used format is not rendered.
-A guideline for creating a good `README` file can be found in the
-[bids-starter-kit](https://github.com/bids-standard/bids-starter-kit/tree/main/templates/).
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___render_text("objects.files.README.description") }}
 
 ### `CHANGES`
 
-Version history of the dataset (describing changes, updates and corrections) MAY
-be provided in the form of a `CHANGES` text file. This file MUST follow the
-[CPAN Changelog convention](https://metacpan.org/pod/release/HAARG/CPAN-Changes-0.400002/lib/CPAN/Changes/Spec.pod).
-The `CHANGES` file MUST be either in ASCII or UTF-8 encoding.
+<!-- This block generates a description.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___render_text("objects.files.CHANGES.description") }}
 
 Example:
 
@@ -190,10 +187,11 @@ Example:
 
 ### `LICENSE`
 
-A `LICENSE` file MAY be provided in addition to the short specification of the
-used license in the `dataset_description.json` `"License"` field.
-The `"License"` field and `LICENSE` file MUST correspond.
-The `LICENSE` file MUST be either in ASCII or UTF-8 encoding.
+<!-- This block generates a description.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___render_text("objects.files.LICENSE.description") }}
 
 ## Participants file
 
@@ -204,23 +202,15 @@ participants.tsv
 participants.json
 ```
 
-The purpose of this RECOMMENDED file is to describe properties of participants
-such as age, sex, handedness, species and strain.
-If this file exists, it MUST contain the column `participant_id`,
-which MUST consist of `sub-<label>` values identifying one row for each participant,
-followed by a list of optional columns describing participants.
-Each participant MUST be described by one and only one row.
-
-The RECOMMENDED `species` column SHOULD be a binomial species name from the
-[NCBI Taxonomy](https://www.ncbi.nlm.nih.gov/Taxonomy/Browser/wwwtax.cgi)
-(for examples `homo sapiens`, `mus musculus`, `rattus norvegicus`).
-For backwards compatibility, if `species` is absent, the participant is assumed to be
-`homo sapiens`.
+<!-- This block generates a description.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___render_text("objects.files.participants.description") }}
 
-Commonly used *optional* columns in `participants.tsv` files are `age`, `sex`,
-`handedness`, `strain`, and `strain_rrid`. We RECOMMEND to make use
-of these columns, and in case that you do use them, we RECOMMEND to use the
-following values for them:
+We RECOMMEND to make use of these columns, and
+in case that you do use them, we RECOMMEND to use the following values
+for them:
 
 <!-- This block generates a columns table.
 The definitions of these fields can be found in
@@ -293,9 +283,11 @@ samples.tsv
 samples.json
 ```
 
-The purpose of this file is to describe properties of samples, indicated by the `sample` entity.
-This file is REQUIRED if `sample-<label>` is present in any filename within the dataset.
-Each sample MUST be described by one and only one row.
+<!-- This block generates a description.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___render_text("objects.files.samples.description") }}
 
 <!-- This block generates a columns table.
 The definitions of these fields can be found in

src/modality-specific-files/genetic-descriptor.md

@@ -83,12 +83,13 @@ Template:
 genetic_info.json
 ```
 
-The `genetic_info.json` file describes the genetic information available in the
-`participants.tsv` file and/or the genetic database described in
-`dataset_description.json`.
-Datasets containing the `Genetics` field in `dataset_description.json` or the
-`genetic_id` column in `participants.tsv` MUST include this file with the following
-fields:
+The following fields are defined for genetic_info.json:
+
+<!-- This block generates a description.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___render_text("objects.files.genetic_info.description") }}
 
 <!-- This block generates a metadata table.
 The definitions of these fields can be found in

src/schema/objects/files.yaml

@@ -50,82 +50,35 @@ genetic_info:
     The `genetic_info.json` file describes the genetic information available in the
     `participants.tsv` file and/or the genetic database described in
     `dataset_description.json`.
+
     Datasets containing the `Genetics` field in `dataset_description.json` or the
     `genetic_id` column in `participants.tsv` MUST include this file.
 participants:
   display_name: Participant Information
   file_type: regular
   description: |
     The purpose of this RECOMMENDED file is to describe properties of participants
-    such as age, sex, handedness.
+    such as age, sex, handedness, species and strain.
     If this file exists, it MUST contain the column `participant_id`,
     which MUST consist of `sub-<label>` values identifying one row for each participant,
     followed by a list of optional columns describing participants.
     Each participant MUST be described by one and only one row.
 
-    Commonly used *optional* columns in `participant.tsv` files are `age`, `sex`,
-    and `handedness`. We RECOMMEND to make use of these columns, and
-    in case that you do use them, we RECOMMEND to use the following values
-    for them:
-
-    -   `age`: numeric value in years (float or integer value)
-
-    -   `sex`: string value indicating phenotypical sex, one of "male", "female",
-        "other"
-
-        -   for "male", use one of these values: `male`, `m`, `M`, `MALE`, `Male`
-
-        -   for "female", use one of these values: `female`, `f`, `F`, `FEMALE`,
-            `Female`
-
-        -   for "other", use one of these values: `other`, `o`, `O`, `OTHER`,
-            `Other`
-
-    -   `handedness`: string value indicating one of "left", "right",
-        "ambidextrous"
-
-        -   for "left", use one of these values: `left`, `l`, `L`, `LEFT`, `Left`
-
-        -   for "right", use one of these values: `right`, `r`, `R`, `RIGHT`,
-            `Right`
-
-        -   for "ambidextrous", use one of these values: `ambidextrous`, `a`, `A`,
-            `AMBIDEXTROUS`, `Ambidextrous`
-
-    Throughout BIDS you can indicate missing values with `n/a` (for "not
-    available").
+    Commonly used *optional* columns in `participants.tsv` files are `age`, `sex`,
+    `handedness`, `strain`, and `strain_rrid`.
 
+    The RECOMMENDED `species` column SHOULD be a binomial species name from the
+    [NCBI Taxonomy](https://www.ncbi.nlm.nih.gov/Taxonomy/Browser/wwwtax.cgi)
+    (for examples `homo sapiens`, `mus musculus`, `rattus norvegicus`).
+    For backwards compatibility, if `species` is absent, the participant is assumed to be
+    `homo sapiens`.
 samples:
   display_name: Sample Information
   file_type: regular
   description: |
     The purpose of this file is to describe properties of samples, indicated by the `sample` entity.
     This file is REQUIRED if `sample-<label>` is present in any filename within the dataset.
-    If this file exists, it MUST contain the three following columns:
-
-    -   `sample_id`: MUST consist of `sample-<label>` values identifying one row
-        for each sample
-
-    -   `participant_id`: MUST consist of `sub-<label>`
-
-    -   `sample_type`: MUST consist of sample type values, either `cell line`, `in vitro differentiated cells`,
-        `primary cell`, `cell-free sample`, `cloning host`, `tissue`, `whole organisms`, `organoid` or
-        `technical sample` from [ENCODE Biosample Type](https://www.encodeproject.org/profiles/biosample_type)
-
-    Other optional columns MAY be used to describe the samples.
     Each sample MUST be described by one and only one row.
-
-    Commonly used *optional* columns in `samples.tsv` files are `pathology` and
-    `derived_from`. We RECOMMEND to make use of these columns, and in case that
-    you do use them, we RECOMMEND to use the following values for them:
-
-    -   `pathology`: string value describing the pathology of the sample or type of control.
-        When different from `healthy`, pathology SHOULD be specified in `samples.tsv`.
-        The pathology MAY instead be specified in
-        [Sessions files](SPEC_ROOT/modality-agnostic-files.md#sessions-file) in case it changes over time.
-
-    -   `derived_from`: `sample-<label>` key/value pair from which a sample is derived from,
-        for example a slice of tissue (`sample-02`) derived from a block of tissue (`sample-01`)
 code:
   display_name: Code
   file_type: directory

tools/mkdocs_macros_bids/__init__.py

@@ -5,6 +5,7 @@
     make_filetree_example,
     make_metadata_table,
     make_suffix_table,
+    render_text,
 )
 from .main import define_env
 
@@ -16,4 +17,5 @@
     "make_suffix_table",
     "make_metadata_table",
     "make_filetree_example",
+    "render_text",
 ]

tools/mkdocs_macros_bids/macros.py

@@ -364,3 +364,12 @@ def define_allowed_top_directories(src_path=None):
     schema_obj = schema.load_schema()
     string = render.define_allowed_top_directories(schema_obj, src_path=src_path)
     return string
+
+
+def render_text(key, src_path=None):
+    if src_path is None:
+        src_path = _get_source_path()
+
+    schema_obj = schema.load_schema()
+    string = render.render_text(schema_obj, key, src_path=src_path)
+    return string

tools/mkdocs_macros_bids/main.py

@@ -46,3 +46,4 @@ def define_env(env):
     env.macro(
         macros.define_allowed_top_directories, "MACROS___define_allowed_top_directories"
     )
+    env.macro(macros.render_text, "MACROS___render_text")

tools/schemacode/bidsschematools/render/__init__.py

@@ -13,6 +13,7 @@
     make_entity_definitions,
     make_filename_template,
     make_glossary,
+    render_text,
 )
 
 __all__ = [
@@ -27,4 +28,5 @@
     "make_filename_template",
     "define_common_principles",
     "define_allowed_top_directories",
+    "render_text",
 ]

tools/schemacode/bidsschematools/render/text.py

@@ -528,3 +528,34 @@ def define_allowed_top_directories(schema, src_path=None) -> str:
             string += f"- `{dirname}`: {definition.description}"
 
     return string.replace("SPEC_ROOT", utils.get_relpath(src_path))
+
+
+def render_text(schema, key: str, src_path=None):
+    """
+
+    Parameters
+    ----------
+    schema : dict
+        The BIDS schema.
+
+    object : str
+        The object to render the description for:
+        possible values correspond to the keys in schema["objects"].
+
+    key : str
+        The key of the object to render the description for:
+        possible values correspond to the keys in schema["objects"][object]
+
+    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
+    -------
+    desc : str
+        Description of the object.
+    """
+    text = schema.get(key)
+    if not isinstance(text, str):
+        raise ValueError(f"{key} does not refer to a text field")
+    return text.replace("SPEC_ROOT", utils.get_relpath(src_path))

tools/schemacode/bidsschematools/tests/test_render_text.py

@@ -1,6 +1,8 @@
 """Tests for the bidsschematools package."""
 import os
 
+import pytest
+
 from bidsschematools.render import text
 
 
@@ -130,3 +132,17 @@ def test_define_allowed_top_directories(schema_obj):
     """smoke test for allowed top directories."""
     test_str = text.define_allowed_top_directories(schema_obj)
     assert isinstance(test_str, str)
+
+
+def test_render_text(schema_obj):
+    test_str = text.render_text(
+        schema_obj, key="objects.files.dataset_description.description", src_path=None
+    )
+    assert (
+        test_str == "The file `dataset_description.json` is a JSON file describing the dataset.\n"
+    )
+
+
+def test_render_text_errors(schema_obj):
+    with pytest.raises(ValueError, match="does not refer to a text field"):
+        text.render_text(schema_obj, key="dataset_description", src_path=None)