From 2a76fb63966ee7419aa6443b579bf051db0661af Mon Sep 17 00:00:00 2001 From: ReenigneArcher <42013603+ReenigneArcher@users.noreply.github.com> Date: Mon, 15 Sep 2025 20:45:38 -0400 Subject: [PATCH] docs: render github admonitions in markdown files --- docs/source/community/community_rules.md | 2 + docs/source/community/community_rules.rst | 2 - docs/source/conf.py | 64 ++++++++++++++++++++++ docs/source/developers/code_of_conduct.md | 2 + docs/source/developers/code_of_conduct.rst | 2 - docs/source/developers/contributing.md | 2 + docs/source/developers/contributing.rst | 2 - 7 files changed, 70 insertions(+), 6 deletions(-) create mode 100644 docs/source/community/community_rules.md delete mode 100644 docs/source/community/community_rules.rst create mode 100644 docs/source/developers/code_of_conduct.md delete mode 100644 docs/source/developers/code_of_conduct.rst create mode 100644 docs/source/developers/contributing.md delete mode 100644 docs/source/developers/contributing.rst diff --git a/docs/source/community/community_rules.md b/docs/source/community/community_rules.md new file mode 100644 index 00000000..74586742 --- /dev/null +++ b/docs/source/community/community_rules.md @@ -0,0 +1,2 @@ +```{include} ../../../COMMUNITY_RULES.md +``` diff --git a/docs/source/community/community_rules.rst b/docs/source/community/community_rules.rst deleted file mode 100644 index d8c869ae..00000000 --- a/docs/source/community/community_rules.rst +++ /dev/null @@ -1,2 +0,0 @@ -.. include:: ../../../COMMUNITY_RULES.md - :parser: myst_parser.docutils_ diff --git a/docs/source/conf.py b/docs/source/conf.py index fae3fdb6..27b9a3c6 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -39,6 +39,11 @@ 'sphinx_copybutton', # add a copy button to code blocks ] +# https://myst-parser.readthedocs.io/en/latest/syntax/optional.html +myst_enable_extensions = [ + "colon_fence", # Only enabled so we can implement am adhoc fix to render GitHub admonitions +] + # Add any paths that contain templates here, relative to this directory. # templates_path = ['_templates'] @@ -94,3 +99,62 @@ # disable epub mimetype warnings # https://github.com/readthedocs/readthedocs.org/blob/eadf6ac6dc6abc760a91e1cb147cc3c5f37d1ea8/docs/conf.py#L235-L236 suppress_warnings = ["epub.unknown_project_files"] + + +# Issue https://github.com/executablebooks/MyST-Parser/issues/845 +# GitHub admonitions with Sphinx/MyST +# Workaround template adapted from (with some changes): +# https://github.com/python-project-templates/yardang/blob/f77348d45dcf0eb130af304f79c0bfb92ab90e0c/yardang/conf.py.j2#L156-L188 + +# https://spdx.github.io/spdx-spec/v2.3/file-tags/#h3-snippet-tags-format +# SPDX-SnippetBegin +# SPDX-License-Identifier: Apache-2.0 +# SPDX-SnippetCopyrightText: Tim Paine / the yardang authors + +_GITHUB_ADMONITIONS = { + "> [!NOTE]": "note", + "> [!TIP]": "tip", + "> [!IMPORTANT]": "important", + "> [!WARNING]": "warning", + "> [!CAUTION]": "caution", +} + + +def convert_gh_admonitions(app, relative_path, parent_docname, contents): + # TODO handle nested directives -> recursion + # loop through content lines, replace github admonitions + for i, orig_content in enumerate(contents): + orig_line_splits = orig_content.split("\n") + replacing = False + for j, line in enumerate(orig_line_splits): + # look for admonition key + line_roi = line.lstrip() + for admonition_key in _GITHUB_ADMONITIONS: + if line_roi.startswith(admonition_key): + line = line.replace(admonition_key, ":::{" + _GITHUB_ADMONITIONS[admonition_key] + "}") + # start replacing quotes in subsequent lines + replacing = True + break + else: # no break + if not replacing: + continue + # remove GH directive to match MyST directive + # since we are replacing on the original line, this will preserve the right indent, if any + if line_roi.startswith("> "): + line = line.replace("> ", "", 1) + elif line_roi.rstrip() == ">": + line = line.replace(">", "", 1) + else: + # missing "> ", so stop replacing and terminate directive + line = f":::\n{line}" + replacing = False + # swap line back in splits + orig_line_splits[j] = line + # swap line back in original + contents[i] = "\n".join(orig_line_splits) + +# SPDX-SnippetEnd + + +def setup(app): + app.connect("include-read", convert_gh_admonitions) diff --git a/docs/source/developers/code_of_conduct.md b/docs/source/developers/code_of_conduct.md new file mode 100644 index 00000000..03ce547a --- /dev/null +++ b/docs/source/developers/code_of_conduct.md @@ -0,0 +1,2 @@ +```{include} ../../../CODE_OF_CONDUCT.md +``` diff --git a/docs/source/developers/code_of_conduct.rst b/docs/source/developers/code_of_conduct.rst deleted file mode 100644 index 8f0c9db4..00000000 --- a/docs/source/developers/code_of_conduct.rst +++ /dev/null @@ -1,2 +0,0 @@ -.. include:: ../../../CODE_OF_CONDUCT.md - :parser: myst_parser.docutils_ diff --git a/docs/source/developers/contributing.md b/docs/source/developers/contributing.md new file mode 100644 index 00000000..004f419c --- /dev/null +++ b/docs/source/developers/contributing.md @@ -0,0 +1,2 @@ +```{include} ../../../CONTRIBUTING.md +``` diff --git a/docs/source/developers/contributing.rst b/docs/source/developers/contributing.rst deleted file mode 100644 index d267ba88..00000000 --- a/docs/source/developers/contributing.rst +++ /dev/null @@ -1,2 +0,0 @@ -.. include:: ../../../CONTRIBUTING.md - :parser: myst_parser.docutils_