Merge pull request #28 from python-project-templates/tkp/admonitions

Add github admonition translation

docs/src/configuration.md

@@ -168,3 +168,26 @@ graph TD;
   B-->D;
   C-->D;
 ```
+
+
+## GitHub Admonitions
+
+GitHub admonitions are automatically translated to sphinx.
+
+> [!NOTE]
+> Note content
+
+> [!TIP]
+> Tip content
+
+> [!IMPORTANT]
+> Important content
+
+> [!WARNING]
+> Warning content
+
+> [!CAUTION]
+> Caution content
+
+
+

yardang/conf.py.j2

@@ -147,8 +147,45 @@ def run_add_version_links_to_toctree(app, doctree):
             nodes[-1]["entries"].append((None, toc_entry))
             nodes[-1]["includefiles"].append(toc_entry)
 
+
+_GITHUB_ADMONITIONS = {
+    "> [!NOTE]": "note",
+    "> [!TIP]": "tip",
+    "> [!IMPORTANT]": "important",
+    "> [!WARNING]": "warning",
+    "> [!CAUTION]": "caution",
+}
+
+def run_convert_github_admonitions_to_rst(app, filename, lines):
+    # loop through lines, replace github admonitions
+    for i, orig_line in enumerate(lines):
+        orig_line_splits = orig_line.split("\n")
+        replacing = False
+        for j, line in enumerate(orig_line_splits):
+            # look for admonition key
+            for admonition_key in _GITHUB_ADMONITIONS:
+                if admonition_key in line:
+                    line = line.replace(admonition_key, "\n```{}\n.. {}::\n".format("{eval-rst}", _GITHUB_ADMONITIONS[admonition_key]))
+                    # start replacing quotes in subsequent lines
+                    replacing = True
+                    break
+            else:
+                # replace indent to match directive
+                if replacing and "> " in line:
+                    line = line.replace("> ", "  ")
+                elif replacing:
+                    # missing "> ", so stop replacing and terminate directive
+                    line = f"\n```\n{line}"
+                    replacing = False
+            # swap line back in splits
+            orig_line_splits[j] = line
+        # swap line back in original
+        lines[i] = "\n".join(orig_line_splits)
+
+
 def setup(app):
     {# app.connect("builder-inited", run_create_previous_version_markdown) #}
     app.connect("builder-inited", run_copyreadme)
     app.connect("builder-inited", run_copycname)
+    app.connect("source-read", run_convert_github_admonitions_to_rst)
     {# app.connect("doctree-read", run_add_version_links_to_toctree, priority=500) #}