added script for converting admonitions to myst

.gitignore

@@ -61,6 +61,7 @@ docs/build/
 docs/source/examples/
 docs/source/api/
 docs/source/api_index.rst
+docs/source/snippets/admonitions.md
 sg_execution_times.rst
 
 # MkDocs documentation

CONTRIBUTING.md

@@ -296,9 +296,13 @@ make html
 ```
 The local build can be viewed by opening `docs/build/html/index.html` in a browser.
 
-To re-build the documentation after making changes, we recommend removing existing build files first.
+To re-build the documentation after making changes,
+we recommend removing existing build files first.
 The following command will remove all generated files in `docs/`,
-including the auto-generated API index `source/api_index.rst`, and those in `build/`, `source/api/`, and `source/examples/`. It will then re-build the documentation:
+including the auto-generated files `source/api_index.rst` and
+`source/snippets/admonitions.md`, as well as all files in
+ `build/`, `source/api/`, and `source/examples/`.
+ It will then re-build the documentation:
 
 ```sh
 make clean html

README.md

@@ -34,6 +34,8 @@ We aim to support a range of pose estimation packages, along with 2D or 3D track
 
 Find out more on our [mission and scope](https://movement.neuroinformatics.dev/community/mission-scope.html) statement and our [roadmap](https://movement.neuroinformatics.dev/community/roadmaps.html).
 
+<!-- Start Admonitions -->
+
 > [!Warning]
 > 🏗️ The package is currently in early development and the interface is subject to change. Feel free to play around and provide feedback.
 
@@ -43,6 +45,8 @@ Find out more on our [mission and scope](https://movement.neuroinformatics.dev/c
 > We are working together with its developer
 > to gradually converge on common data standards and workflows.
 
+<!-- End Admonitions -->
+
 ## Join the movement
 
 Contributions to movement are absolutely encouraged, whether to fix a bug, develop a new feature, or improve the documentation.

docs/Makefile

@@ -19,14 +19,20 @@ help:
 api_index.rst:
 	python make_api_index.py
 
+# Generate the snippets/admonitions.md file
+# by converting the admonitions in the repo's README.md to MyST format
+admonitions.md:
+	python convert_admonitions.py
+
 # Remove all generated files
 clean:
 	rm -rf ./build
 	rm -f ./source/api_index.rst
 	rm -rf ./source/api
 	rm -rf ./source/examples
+	rm -rf ./source/snippets/admonitions.md
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile api_index.rst
+%: Makefile api_index.rst admonitions.md
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/convert_admonitions.py

@@ -0,0 +1,87 @@
+"""Convert admonitions GitHub Flavored Markdown to MyST Markdown."""
+
+import re
+from pathlib import Path
+
+
+def convert_gfm_admonitions_to_myst_snippets(
+    input_path: Path, output_path: Path, exclude: set[str] | None = None
+):
+    """Convert admonitions from GitHub Flavored Markdown to MyST.
+
+    Extracts GitHub Flavored Markdown admonitions from the input file and
+    writes them to the output file as MyST Markdown admonitions.
+    The original admonition type and order are preserved.
+
+    Parameters
+    ----------
+    input_path : Path
+        Path to the input file containing GitHub Flavored Markdown.
+    output_path : Path
+        Path to the output file to write the MyST Markdown admonitions.
+    exclude : set[str], optional
+        Set of admonition types to exclude from conversion (case-insensitive).
+        Default is None.
+
+    """
+    valid_types = {"note", "tip", "important", "warning", "caution"}
+    if exclude is None:
+        excluded_types = set()  # Empty set
+    else:
+        excluded_types = set([s.lower() for s in exclude])  # Lowercase
+
+    print(f"Excluded admonition types: {excluded_types}")
+
+    # Read the input file
+    with open(input_path, encoding="utf-8") as f:
+        gfm_text = f.read()
+
+    # Regex pattern to match GFM admonitions
+    pattern = r"(^> \[!(\w+)\]\n(?:^> .*\n?)*)"
+    matches = re.finditer(pattern, gfm_text, re.MULTILINE)
+
+    # List to hold converted admonitions
+    admonitions = []
+
+    for match in matches:
+        full_block = match.group(0)
+        adm_type = match.group(2).lower()
+        # Skip invalid or excluded admonition types
+        if adm_type not in valid_types or adm_type in excluded_types:
+            continue
+        # Extract content lines, skipping the admonition type line
+        content_lines = []
+        for line in full_block.split("\n"):
+            if line.startswith("> ") and not line.startswith("> [!"):
+                content_lines.append(line[2:].strip())
+        content = "\n".join(content_lines).strip()
+        # Convert to MyST admonition
+        adm_myst = ":::{" + adm_type + "}\n" + content + "\n" + ":::\n"
+        # Append to the list
+        admonitions.append(adm_myst)
+
+    if admonitions:
+        # Write all admonitions to a single file
+        with open(output_path, "w", encoding="utf-8") as f:
+            for admonition in admonitions:
+                f.write(admonition + "\n")
+        print(f"Admonitions written to {output_path}")
+    else:
+        print("No GitHub Markdown admonitions found.")
+
+
+if __name__ == "__main__":
+    # Path to the README.md file
+    # (1 level above the current script)
+    docs_dir = Path(__file__).resolve().parent
+    readme_path = docs_dir.parent / "README.md"
+
+    # Path to the output file
+    # (inside the docs/source/snippets directory)
+    snippets_dir = docs_dir / "source" / "snippets"
+    target_path = snippets_dir / "admonitions.md"
+
+    # Call the function
+    convert_gfm_admonitions_to_myst_snippets(
+        readme_path, target_path, exclude={"note"}
+    )

docs/make.bat

@@ -28,14 +28,19 @@ if "%1" == "" goto help
 
 :process_targets
 if "%1" == "clean" (
-	@echo Removing auto-generated files under 'docs' and 'src'...
+	echo Removing auto-generated files...
 	rmdir /S /Q %BUILDDIR%
 	del /Q %SOURCEDIR%\api_index.rst
     rmdir /S /Q %SOURCEDIR%\api\
 	rmdir /S /Q %SOURCEDIR%\examples\
+    del /Q %SOURCEDIR%\snippets\admonitions.md
 ) else (
-	@echo Generating API index...
+	echo Generating API index...
 	python make_api_index.py
+
+	echo Converting admonitions...
+    python convert_admonitions.py
+
 	%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 )
 

docs/source/index.md

@@ -39,10 +39,7 @@ We aim to support a range of pose estimation packages, along with 2D or 3D track
 
 Find out more on our [mission and scope](target-mission) statement and our [roadmap](target-roadmaps).
 
-```{include} /snippets/status-warning.md
-```
-
-```{include} /snippets/animovement-tip.md
+```{include} /snippets/admonitions.md
 ```
 
 ## Citation