Merge branch 'bids-standard:master' into master

.gitignore

@@ -7,6 +7,7 @@ venvs
 pdf_build_src/bids-spec.pdf
 pdf_build_src/bids-spec_pandoc_log.json
 pdf_build_src/src_copy
+pdf_build_src/tests/data/output
 
 # JS/NPM
 package-lock.json

.pre-commit-config.yaml

@@ -13,7 +13,7 @@ repos:
       - id: check-added-large-files
       - id: check-case-conflict
   - repo: https://github.com/psf/black
-    rev: 24.2.0
+    rev: 24.3.0
     hooks:
       - id: black
         files: ^tools/(?!schemacode)

.remarkrc

@@ -10,6 +10,7 @@
     ["lint-maximum-heading-length", false],
     ["lint-no-shortcut-reference-link", false],
     ["lint-no-trailing-spaces"],
+    ["remark-lint-code-block-style", false],
     ["lint-no-undefined-references", false]
   ]
 }

CONTRIBUTING.md

@@ -226,6 +226,37 @@ That would look like this:
 |--------------|----------------------------------------------------------|
 | Manufacturer | Manufacturer of the equipment, for example (`"Siemens"`) |
 
+
+#### MkDocs admonitions
+
+It is possible to use [Mkdocs admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#inline-blocks-inline-end)
+to highlight certain aspect of the specification.
+
+Admonitions are written like this:
+
+````
+!!! note "displayed heading is preceded by a keyword and 3 `!`"
+
+    Body of the admonition
+    can be written on several lines,
+    but must be always preceded by 4 spaces.
+````
+
+The keyword for the heading must be one of the following:
+
+- note
+- abstract
+- info
+- tip
+- success
+- question
+- warning
+- failure: octicons
+- danger
+- bug
+- example
+- quote
+
 ## Using macros
 
 We use [mkdocs-macros](https://mkdocs-macros-plugin.readthedocs.io/en/latest/)

mkdocs.yml

@@ -101,6 +101,8 @@ markdown_extensions:
   - toc:
       anchorlink: true
   - pymdownx.superfences
+  - admonition
+  - pymdownx.details
 plugins:
   - search
   - branchcustomization:

pdf_build_src/pandoc_script.py

@@ -2,6 +2,7 @@
 
 This is done once the duplicate src directory is processed.
 """
+
 import subprocess
 import yaml
 from pathlib import Path
@@ -11,9 +12,7 @@
 
 def _find(path, filename):
     return next(
-        parent / filename
-        for parent in path.parents
-        if Path.is_file(parent / filename)
+        parent / filename for parent in path.parents if Path.is_file(parent / filename)
     )
 
 

pdf_build_src/process_markdowns.py

@@ -17,6 +17,8 @@
 
 import numpy as np
 
+from remove_admonitions import remove_admonitions
+
 sys.path.append("../tools/")
 # functions from module macros are called by eval() later on
 from mkdocs_macros_bids import macros  # noqa: F401
@@ -585,9 +587,9 @@ def edit_titlepage():
         data = file.readlines()
 
     data[-1] = (
-        fr"\textsc{{\large {version_number}}}"
+        rf"\textsc{{\large {version_number}}}"
         r"\\[0.5cm]"
-        fr"{{\large {build_date}}}"
+        rf"{{\large {build_date}}}"
         r"\\[2cm]"
         r"\vfill"
         r"\end{titlepage}"
@@ -679,33 +681,38 @@ def process_macros(duplicated_src_dir_path):
 
     duplicated_src_dir_path = "src_copy/src"
 
-    # Step 1: make a copy of the src directory in the current directory
+    # make a copy of the src directory in the current directory
     copy_src()
 
-    # Step 2: run mkdocs macros embedded in markdown files
+    # run mkdocs macros embedded in markdown files
     process_macros(duplicated_src_dir_path)
 
-    # Step 3: copy BIDS_logo to images directory of the src_copy directory
+    # remove mkdocs admonition
+    remove_admonitions(
+        input_folder=duplicated_src_dir_path, output_folder=duplicated_src_dir_path
+    )
+
+    # copy BIDS_logo to images directory of the src_copy directory
     copy_bids_logo()
 
-    # Step 4: copy images from subdirectories of src_copy directory
+    # copy images from subdirectories of src_copy directory
     copy_images(duplicated_src_dir_path)
     subprocess.call("mv src_copy/src/images/images/* src_copy/src/images/", shell=True)
 
-    # Step 5: extract the latest version number, date and title
+    # extract the latest version number, date and title
     extract_header_string()
     add_header()
 
     edit_titlepage()
 
-    # Step 6: modify changelog to be a level 1 heading to facilitate section
+    # modify changelog to be a level 1 heading to facilitate section
     # separation
     modify_changelog()
 
-    # Step 7: remove all internal links
+    # remove all internal links
     assert_no_multiline_links(duplicated_src_dir_path)
     remove_internal_links_inline(duplicated_src_dir_path)
     remove_internal_links_reference(duplicated_src_dir_path)
 
-    # Step 8: correct number of dashes and fences alignment for rendering tables in PDF
+    # correct number of dashes and fences alignment for rendering tables in PDF
     correct_tables(duplicated_src_dir_path)

pdf_build_src/remove_admonitions.py

@@ -0,0 +1,64 @@
+"""Script to remove all mkdocs admonition from the markdown files in a directory.
+
+See the pdf_build_src/tests/data/input directory to see what admonitions look like.
+"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+INDENT = "    "
+
+ADMONITION_DELIMITERS = ["!!!", "???", "???+"]
+
+
+def remove_admonitions(
+    input_folder: str | Path, output_folder: str | Path, indent: str = None
+):
+
+    if indent is None:
+        indent = INDENT
+
+    md_files = Path(input_folder).glob("**/*.md")
+
+    for file in md_files:
+
+        with open(file, "r", encoding="utf8") as f:
+            content = f.readlines()
+
+        output_file = Path(output_folder) / file.relative_to(input_folder)
+        output_file.parent.mkdir(parents=True, exist_ok=True)
+        print(f"processing: {file}\n to: {output_file}")
+
+        with open(output_file, "w", encoding="utf8") as f:
+
+            is_admonition = False
+            counter = 0
+            for line in content:
+
+                if any(line.startswith(x) for x in ADMONITION_DELIMITERS):
+                    is_admonition = True
+                    counter = 0
+                    continue
+
+                # skip first line after admonition
+                if is_admonition and counter == 0:
+                    counter += 1
+                    continue
+
+                if not line.startswith(indent):
+                    is_admonition = False
+
+                if is_admonition:
+                    line = line.lstrip(indent)
+
+                f.write(line)
+
+
+if __name__ == "__main__":
+    """If run as a script this will just run the main function on test data."""
+    input_folder = Path(__file__).parent / "tests" / "data" / "input"
+    output_folder = Path(__file__).parent / "tests" / "data" / "output"
+    shutil.rmtree(output_folder)
+    remove_admonitions(input_folder, output_folder)

pdf_build_src/test_remove_admonitions.py

@@ -0,0 +1,25 @@
+from pathlib import Path
+
+from remove_admonitions import remove_admonitions
+
+
+def test_remove_admonitions(tmp_path):
+    input_folder = Path(__file__).parent / "tests" / "data" / "input"
+    expected_folder = Path(__file__).parent / "tests" / "data" / "expected"
+
+    remove_admonitions(input_folder, tmp_path)
+
+    generated_files = list(tmp_path.glob("**/*.md"))
+
+    for file in generated_files:
+
+        expected = expected_folder / file.relative_to(tmp_path)
+
+        with open(expected, "r", encoding="utf8") as f:
+            expected_content = f.readlines()
+
+        with open(file, "r", encoding="utf8") as f:
+            generated_content = f.readlines()
+
+        for expected_line, generated_line in zip(expected_content, generated_content):
+            assert generated_line == expected_line

pdf_build_src/tests/data/expected/README.md

@@ -0,0 +1,21 @@
+# Test inputs
+
+This input directory contains data to use for testing the pdf build code of the BIDS specification.
+
+For example the following admonition should be removed by `pdf_build_src/remove_admonitions.py`.
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+Nulla et euismod nulla.
+Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa,
+nec semper lorem quam in massa.
+
+The `expected` directory should contain the documents
+as they should look like after processing.
+
+[Mkdocs admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#inline-blocks-inline-end)
+come in different type. In aaddtion of the classical admonitions show above you have also:
+
+Collapsible admonitions start with 3 questions marks (`???`).
+
+Collapsible admonitions that will be shown as expanded
+start with 3 questions marks and a plus sign (`???+`).

pdf_build_src/tests/data/expected/modality-specific-files/magnetic-resonance-imaging-data.md

@@ -0,0 +1,8 @@
+# Magnetic Resonance Imaging
+
+## Common metadata fields
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+Nulla et euismod nulla.
+Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa,
+nec semper lorem quam in massa.

pdf_build_src/tests/data/input/README.md

@@ -0,0 +1,27 @@
+# Test inputs
+
+This input directory contains data to use for testing the pdf build code of the BIDS specification.
+
+For example the following admonition should be removed by `pdf_build_src/remove_admonitions.py`.
+
+!!! note
+
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+    Nulla et euismod nulla.
+    Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa,
+    nec semper lorem quam in massa.
+
+The `expected` directory should contain the documents
+as they should look like after processing.
+
+[Mkdocs admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#inline-blocks-inline-end)
+come in different type. In aaddtion of the classical admonitions show above you have also:
+
+??? note "Collapsible admonitions"
+
+    Collapsible admonitions start with 3 questions marks (`???`).
+
+???+ note "Expanded collapsible admonitions"
+
+    Collapsible admonitions that will be shown as expanded
+    start with 3 questions marks and a plus sign (`???+`).

pdf_build_src/tests/data/input/modality-specific-files/magnetic-resonance-imaging-data.md

@@ -0,0 +1,10 @@
+# Magnetic Resonance Imaging
+
+## Common metadata fields
+
+!!! warning "foo bar"
+
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+    Nulla et euismod nulla.
+    Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa,
+    nec semper lorem quam in massa.

src/modality-specific-files/electroencephalography.md

@@ -6,9 +6,11 @@ Please see [Citing BIDS](../introduction.md#citing-bids)
 on how to appropriately credit this extension when referring to it in the
 context of the academic literature.
 
-Several [example EEG datasets](https://bids-standard.github.io/bids-examples/#eeg)
-have been formatted using this specification
-and can be used for practical guidance when curating a new dataset.
+!!! example "Example datasets"
+
+    Several [example EEG datasets](https://bids-standard.github.io/bids-examples/#eeg)
+    have been formatted using this specification
+    and can be used for practical guidance when curating a new dataset.
 
 ## EEG recording data
 

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

@@ -12,10 +12,12 @@ A genetic descriptor links a BIDS dataset to associated genetic data,
 potentially in a separate repository,
 with details of where to find the genetic data and the type of data available.
 
-The following example dataset with genetics data have been formatted using this specification
-and can be used for practical guidance when curating a new dataset.
+!!! example "Example datasets"
 
--   [`UK biobank`](https://github.com/bids-standard/bids-examples/tree/master/genetics_ukbb)
+    The following example dataset with genetics data have been formatted using this specification
+    and can be used for practical guidance when curating a new dataset.
+
+    -   [`UK biobank`](https://github.com/bids-standard/bids-examples/tree/master/genetics_ukbb)
 
 ## Dataset Description
 

src/modality-specific-files/intracranial-electroencephalography.md

@@ -6,9 +6,11 @@ Please see [Citing BIDS](../introduction.md#citing-bids)
 on how to appropriately credit this extension when referring to it in the
 context of the academic literature.
 
-Several [example iEEG datasets](https://bids-standard.github.io/bids-examples/#ieeg)
-have been formatted using this specification
-and can be used for practical guidance when curating a new dataset.
+!!! example "Example datasets"
+
+    Several [example iEEG datasets](https://bids-standard.github.io/bids-examples/#ieeg)
+    have been formatted using this specification
+    and can be used for practical guidance when curating a new dataset.
 
 ## iEEG recording data