diff --git a/.gitignore b/.gitignore index c46b1d71..6611c73a 100644 --- a/.gitignore +++ b/.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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 63dc93bf..88f5ecd0 100644 --- a/CONTRIBUTING.md +++ b/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 diff --git a/README.md b/README.md index da35dd48..ab66a9b8 100644 --- a/README.md +++ b/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). + + > [!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. + + ## Join the movement Contributions to movement are absolutely encouraged, whether to fix a bug, develop a new feature, or improve the documentation. diff --git a/docs/Makefile b/docs/Makefile index da95f613..df622291 100644 --- a/docs/Makefile +++ b/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) diff --git a/docs/convert_admonitions.py b/docs/convert_admonitions.py new file mode 100644 index 00000000..4e22a5e1 --- /dev/null +++ b/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"} + ) diff --git a/docs/make.bat b/docs/make.bat index b1e18dd6..1969d4b3 100644 --- a/docs/make.bat +++ b/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% ) diff --git a/docs/source/index.md b/docs/source/index.md index 1c9d2d0e..d37c1849 100644 --- a/docs/source/index.md +++ b/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 diff --git a/docs/source/snippets/animovement-tip.md b/docs/source/snippets/animovement-tip.md deleted file mode 100644 index ff600847..00000000 --- a/docs/source/snippets/animovement-tip.md +++ /dev/null @@ -1,7 +0,0 @@ -:::{admonition} Tip for R users -:class: Tip -If you prefer analysing your data in R, we recommend checking out the -[animovement](https://www.roald-arboel.com/animovement/) toolbox, which is similar in scope. -We are working together with its developer -to gradually converge on common data standards and workflows. -::: diff --git a/docs/source/snippets/status-warning.md b/docs/source/snippets/status-warning.md deleted file mode 100644 index a9ccbbb7..00000000 --- a/docs/source/snippets/status-warning.md +++ /dev/null @@ -1,4 +0,0 @@ -:::{admonition} Status -:class: warning -The package is currently in early development and the interface is subject to change. Feel free to play around and provide feedback. -:::