[ENH] allow using of mkdoc admonitions

.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

.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]
   ]
 }

mkdocs.yml

@@ -97,6 +97,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,62 @@
+"""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 = "    "
+
+
+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 line.startswith("!!!"):
+                    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 = [x for x in 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,13 @@
+# 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.

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,15 @@
+# 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.

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
 

src/modality-specific-files/magnetic-resonance-imaging-data.md

@@ -635,14 +635,16 @@ A guide for using macros can be found at
 
 ## Diffusion imaging data
 
-Several [example datasets](https://github.com/bids-standard/bids-examples)
-contain diffusion imaging data formatted using this specification
-and that can be used for practical guidance when curating a new dataset:
+!!! example "Example datasets"
 
--   [`genetics_ukbb`](https://github.com/bids-standard/bids-examples/tree/master/genetics_ukbb)
--   [`eeg_rest_fmri`](https://github.com/bids-standard/bids-examples/tree/master/eeg_rest_fmri)
--   [`ds114`](https://github.com/bids-standard/bids-examples/tree/master/ds114)
--   [`ds000117`](https://github.com/bids-standard/bids-examples/tree/master/ds000117)
+    Several [example datasets](https://github.com/bids-standard/bids-examples)
+    contain diffusion imaging data formatted using this specification
+    and that can be used for practical guidance when curating a new dataset:
+
+    -   [`genetics_ukbb`](https://github.com/bids-standard/bids-examples/tree/master/genetics_ukbb)
+    -   [`eeg_rest_fmri`](https://github.com/bids-standard/bids-examples/tree/master/eeg_rest_fmri)
+    -   [`ds114`](https://github.com/bids-standard/bids-examples/tree/master/ds114)
+    -   [`ds000117`](https://github.com/bids-standard/bids-examples/tree/master/ds000117)
 
 Diffusion-weighted imaging data acquired for a participant.
 Currently supported image types include:
@@ -868,9 +870,11 @@ JSON example:
 
 ## Arterial Spin Labeling perfusion data
 
-Several [example ASL datasets](https://bids-standard.github.io/bids-examples/#asl)
-have been formatted using this specification
-and can be used for practical guidance when curating a new dataset.
+!!! example "Example datasets"
+
+    Several [example ASL datasets](https://bids-standard.github.io/bids-examples/#asl)
+    have been formatted using this specification
+    and can be used for practical guidance when curating a new dataset.
 
 <!--
 This block generates a filename templates.
@@ -1111,12 +1115,14 @@ For example:
 
 #### Case 1: Phase-difference map and at least one magnitude image
 
-[Example datasets](https://bids-standard.github.io/bids-examples/#dataset-index)
-containing that type of fieldmap can be found here:
+!!! example "Example datasets"
 
--   [`7t_trt`](https://github.com/bids-standard/bids-examples/tree/master/7t_trt)
--   [`genetics_ukbb`](https://github.com/bids-standard/bids-examples/tree/master/genetics_ukbb)
--   [`ds000117`](https://github.com/bids-standard/bids-examples/tree/master/ds000117)
+    [Example datasets](https://bids-standard.github.io/bids-examples/#dataset-index)
+    containing that type of fieldmap can be found here:
+
+    -   [`7t_trt`](https://github.com/bids-standard/bids-examples/tree/master/7t_trt)
+    -   [`genetics_ukbb`](https://github.com/bids-standard/bids-examples/tree/master/genetics_ukbb)
+    -   [`ds000117`](https://github.com/bids-standard/bids-examples/tree/master/ds000117)
 
 <!--
 This block generates a filename templates.
@@ -1236,10 +1242,12 @@ for details on the `IntendedFor` field.
 
 #### Case 4: Multiple phase encoded directions ("pepolar")
 
-An [example dataset](https://github.com/bids-standard/bids-examples)
-containing that type of fieldmap can be found here:
+!!! example "Example datasets"
+
+    An [example dataset](https://github.com/bids-standard/bids-examples)
+    containing that type of fieldmap can be found here:
 
--   [`ieeg_visual_multimodal`](https://github.com/bids-standard/bids-examples/tree/master/ieeg_visual_multimodal)
+    -   [`ieeg_visual_multimodal`](https://github.com/bids-standard/bids-examples/tree/master/ieeg_visual_multimodal)
 
 The phase-encoding polarity (PEpolar) technique combines two or more Spin Echo
 EPI scans with different phase encoding directions to estimate the distortion

src/modality-specific-files/magnetoencephalography.md

@@ -6,13 +6,15 @@ 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.
 
-The following example MEG datasets have been formatted using this specification
-and can be used for practical guidance when curating a new dataset.
+!!! example "Example datasets"
 
--   [`multimodal MEG and MRI`](https://github.com/bids-standard/bids-examples/tree/master/ds000117)
+    The following example MEG datasets have been formatted using this specification
+    and can be used for practical guidance when curating a new dataset.
 
-Further datasets are available from
-the [BIDS examples repository](https://bids-standard.github.io/bids-examples/#meg).
+    -   [`multimodal MEG and MRI`](https://github.com/bids-standard/bids-examples/tree/master/ds000117)
+
+    Further datasets are available from
+    the [BIDS examples repository](https://bids-standard.github.io/bids-examples/#meg).
 
 ## MEG recording data