[ENH] use schema to mention which "top directories" are allowed

macros_doc.md

@@ -80,17 +80,19 @@ consistency.
 All the macros we use are in listed in this
 [Python file](https://github.com/bids-standard/bids-specification/blob/master/tools/mkdocs_macros_bids/macros.py).
 
-| Name                     | Purpose                                                                                | Uses schema | Example                                                                                                                                                                                     |
-| ------------------------ | -------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| make_columns_table       | Generate a markdown table of TSV column information.                                   | Yes         | [link](https://github.com/bids-standard/bids-specification/blob/9201b203ffaa72d83b2fa30d1c61f46f089f77de/src/03-modality-agnostic-files.md?plain=1#L202)                                    |
-| make_entity_table        | Generate an entity table from the schema, based on specific filters.                   | Yes         | [link](https://github.com/bids-standard/bids-specification/blob/9201b203ffaa72d83b2fa30d1c61f46f089f77de/src/99-appendices/04-entity-table.md?plain=1#L23)                                  |
-| make_entity_definitions  | Generate definitions and other relevant information for entities in the specification. | Yes         | [link](https://github.com/bids-standard/bids-specification/blob/9201b203ffaa72d83b2fa30d1c61f46f089f77de/src/99-appendices/09-entities.md?plain=1#L16)                                      |
-| make_filename_template   | Generate a filename template from the schema, based on specific filters.               | Yes         | [link](https://github.com/bids-standard/bids-specification/blob/9201b203ffaa72d83b2fa30d1c61f46f089f77de/src/04-modality-specific-files/10-microscopy.md?plain=1#L21)                       |
-| make_filetree_example    | Generate a filetree snippet from example content.                                      | No          | [link](https://github.com/bids-standard/bids-specification/blob/9201b203ffaa72d83b2fa30d1c61f46f089f77de/src/02-common-principles.md?plain=1#L268)                                          |
-| make_glossary            |                                                                                        | Yes         | [link](https://github.com/bids-standard/bids-specification/blob/9201b203ffaa72d83b2fa30d1c61f46f089f77de/src/99-appendices/14-glossary.md?plain=1#L9)                                       |
-| make_metadata_table      | Generate a markdown table of metadata field information.                               | Yes         | [link](https://github.com/bids-standard/bids-specification/blob/9201b203ffaa72d83b2fa30d1c61f46f089f77de/src/02-common-principles.md?plain=1#L462)                                          |
-| 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)                                           |
+| Name                           | Purpose                                                                                | Uses schema | Example                                                                                                                                                                                     |
+| ------------------------------ | -------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| make_columns_table             | Generate a markdown table of TSV column information.                                   | Yes         | [link](https://github.com/bids-standard/bids-specification/blob/9201b203ffaa72d83b2fa30d1c61f46f089f77de/src/03-modality-agnostic-files.md?plain=1#L202)                                    |
+| make_entity_table              | Generate an entity table from the schema, based on specific filters.                   | Yes         | [link](https://github.com/bids-standard/bids-specification/blob/9201b203ffaa72d83b2fa30d1c61f46f089f77de/src/99-appendices/04-entity-table.md?plain=1#L23)                                  |
+| make_entity_definitions        | Generate definitions and other relevant information for entities in the specification. | Yes         | [link](https://github.com/bids-standard/bids-specification/blob/9201b203ffaa72d83b2fa30d1c61f46f089f77de/src/99-appendices/09-entities.md?plain=1#L16)                                      |
+| make_filename_template         | Generate a filename template from the schema, based on specific filters.               | Yes         | [link](https://github.com/bids-standard/bids-specification/blob/9201b203ffaa72d83b2fa30d1c61f46f089f77de/src/04-modality-specific-files/10-microscopy.md?plain=1#L21)                       |
+| make_filetree_example          | Generate a filetree snippet from example content.                                      | No          | [link](https://github.com/bids-standard/bids-specification/blob/9201b203ffaa72d83b2fa30d1c61f46f089f77de/src/02-common-principles.md?plain=1#L268)                                          |
+| make_glossary                  |                                                                                        | Yes         | [link](https://github.com/bids-standard/bids-specification/blob/9201b203ffaa72d83b2fa30d1c61f46f089f77de/src/99-appendices/14-glossary.md?plain=1#L9)                                       |
+| make_metadata_table            | Generate a markdown table of metadata field information.                               | Yes         | [link](https://github.com/bids-standard/bids-specification/blob/9201b203ffaa72d83b2fa30d1c61f46f089f77de/src/02-common-principles.md?plain=1#L462)                                          |
+| 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)                                          |
+
 
 ## When should I use a macro?
 

src/02-common-principles.md

@@ -109,6 +109,17 @@ data type as defined above.
 A data type directory SHOULD NOT be defined if there are no files to be placed
 in that directory.
 
+### Other top level directories
+
+In addition to the subject directories, the root directory of a BIDS dataset
+MAY also contain the following directories:
+
+<!-- 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___define_allowed_top_directories() }}
+
 ## Filenames
 
 A filename consists of a chain of *entity instances* and a *suffix*

src/schema/objects/files.yaml

@@ -130,27 +130,29 @@ code:
   display_name: Code
   file_type: directory
   description: |
-    A directory in which to store any code used to generate the derivatives from the
-    source data.
+    A directory in which to store any code
+    (for example the one used to generate the derivatives from the raw data).
+    See the [Code section](SPEC_ROOT/03-modality-agnostic-files.md#code)
+    for more information.
 derivatives:
   display_name: Derivative data
   file_type: directory
   description: |
-    Derivative data
+    Derivative data (for example preprocessed files).
+    See the [relevant section](SPEC_ROOT/02-common-principles.md#source-vs-raw-vs-derived-data)
+    for more information.
 sourcedata:
   display_name: Source data
   file_type: directory
   description: |
-    Data before harmonization, reconstruction, and/or file format conversion
-    (for example, E-Prime event logs or DICOM files).
+    A directory where to store data before harmonization, reconstruction,
+    and/or file format conversion (for example, E-Prime event logs or DICOM files).
+    See the [relevant section](SPEC_ROOT/02-common-principles.md#source-vs-raw-vs-derived-data)
+    for more information.
 stimuli:
   display_name: Stimulus files
   file_type: directory
   description: |
-    The stimulus files can be added in a `/stimuli` directory
-    (under the root directory of the dataset; with optional subdirectories)
-    AND using a stim_file column in *_events.tsv mentioning which stimulus file was
-    used for a given event.
-
-    There are no restrictions on the file formats of the stimuli files, but they should be
-    stored in the `/stimuli` directory.
+    A directory to store any stimulus files used during an experiment.
+    See the [relevant section](SPEC_ROOT/04-modality-specific-files/05-task-events.md#stimuli-directory)
+    for more information.

tools/mkdocs_macros_bids/macros.py

@@ -348,3 +348,13 @@ def define_common_principles(src_path=None):
     schema_obj = schema.load_schema()
     string = render.define_common_principles(schema_obj, src_path=src_path)
     return string
+
+
+def define_allowed_top_directories(src_path=None):
+
+    if src_path is None:
+        src_path = _get_source_path()
+
+    schema_obj = schema.load_schema()
+    string = render.define_allowed_top_directories(schema_obj, src_path=src_path)
+    return string

tools/mkdocs_macros_bids/main.py

@@ -43,3 +43,4 @@ def define_env(env):
     env.macro(macros.make_columns_table, "MACROS___make_columns_table")
     env.macro(macros.make_filetree_example, "MACROS___make_filetree_example")
     env.macro(macros.define_common_principles, "MACROS___define_common_principles")
+    env.macro(macros.define_allowed_top_directories, "MACROS___define_allowed_top_directories")

tools/schemacode/bidsschematools/render/__init__.py

@@ -8,6 +8,7 @@
     make_suffix_table,
 )
 from bidsschematools.render.text import (
+    define_allowed_top_directories,
     define_common_principles,
     make_entity_definitions,
     make_filename_template,
@@ -25,4 +26,5 @@
     "make_glossary",
     "make_filename_template",
     "define_common_principles",
+    "define_allowed_top_directories",
 ]

tools/schemacode/bidsschematools/render/text.py

@@ -480,3 +480,29 @@ def define_common_principles(schema, src_path=None):
     string = string.replace("SPEC_ROOT", utils.get_relpath(src_path))
 
     return string
+
+
+def define_allowed_top_directories(schema, src_path=None) -> str:
+    """Create a list of allowed top-level directories with their descriptions.
+
+    Parameters
+    ----------
+    schema : dict
+        The BIDS schema.
+    src_path : str | None
+        The file where this macro is called, which may be explicitly provided
+        by the "page.file.src_path" variable.
+
+    Returns
+    -------
+    string : str
+        Unordered list describing top level directories.
+    """
+
+    string = ""
+
+    for dirname, definition in schema.objects.files.items():
+        if definition.file_type == "directory":
+            string += f"- `{dirname}`: {definition.description}"
+
+    return string.replace("SPEC_ROOT", utils.get_relpath(src_path))

tools/schemacode/bidsschematools/tests/test_render_text.py

@@ -124,3 +124,9 @@ def test_append_filename_template_legend():
     test_str = text.append_filename_template_legend("", pdf_format=True)
     assert isinstance(test_str, str)
     assert "follow the links" not in test_str
+
+
+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)