Merge pull request #221 from lsst-sqre/tickets/DM-43617

DM-43617: Fix Source parser for markdown not registered error for technotes

.github/workflows/ci-cron.yaml

@@ -41,11 +41,16 @@ jobs:
           npm install
           npm run build
 
+      - name: Install graphviz
+        run: |
+          sudo apt-get update
+          sudo apt-get install graphviz
+
       - name: Run tests in tox
         uses: lsst-sqre/run-tox@v1
         with:
           python-version: ${{ matrix.python-version }}
-          tox-envs: "lint,typing-sphinx${{ matrix.sphinx-version }},py-test-sphinx${{ matrix.sphinx-version }}"
+          tox-envs: "lint,typing-sphinx${{ matrix.sphinx-version }},py-test-sphinx${{ matrix.sphinx-version }},demo"
           use-cache: false
 
   docs:

.github/workflows/ci.yaml

@@ -61,11 +61,16 @@ jobs:
           npm install
           npm run build
 
+      - name: Install graphviz
+        run: |
+          sudo apt-get update
+          sudo apt-get install graphviz
+
       - name: Run tox
         uses: lsst-sqre/run-tox@v1
         with:
           python-version: ${{ matrix.python-version }}
-          tox-envs: 'py-test-sphinx${{ matrix.sphinx-version }},typing-sphinx${{ matrix.sphinx-version }}'
+          tox-envs: 'py-test-sphinx${{ matrix.sphinx-version }},typing-sphinx${{ matrix.sphinx-version }},demo'
 
   docs:
     runs-on: ubuntu-latest

CHANGELOG.md

@@ -2,6 +2,13 @@
 
 <!-- scriv-insert-here -->
 
+<a id='changelog-1.2.1'></a>
+## 1.2.1 (2024-04-02)
+
+### Bug fixes
+
+- Fix the "Source parser for markdown not registered" error for Markdown-based technotes. With the MyST-NB extension the Markdown parser is automatically registered, so the `documenteer.conf.technote` configuration now resets the `source_suffix` configuration originally created by the Technote package.
+
 <a id='changelog-1.2.0'></a>
 ## 1.2.0 (2024-03-26)
 

demo/md-technote/.gitignore

@@ -0,0 +1,2 @@
+_build
+.technote

demo/md-technote/Makefile

@@ -0,0 +1,3 @@
+.PHONY:
+clean:
+	rm -rf _build

demo/md-technote/conf.py

@@ -0,0 +1 @@
+from documenteer.conf.technote import *  # noqa F401 F403

demo/md-technote/diagram.py

@@ -0,0 +1,14 @@
+from diagrams.k8s.clusterconfig import HPA
+from diagrams.k8s.compute import Deployment, Pod, ReplicaSet
+from diagrams.k8s.network import Ingress, Service
+from sphinx_diagrams import SphinxDiagram
+
+with SphinxDiagram(title="GKE"):
+    net = Ingress("domain.com") >> Service("svc")
+    (
+        net
+        >> [Pod("pod1"), Pod("pod2"), Pod("pod3")]
+        << ReplicaSet("rs")
+        << Deployment("dp")
+        << HPA("hpa")
+    )

demo/md-technote/index.md

@@ -0,0 +1,73 @@
+# Demo technote
+
+```{abstract}
+A *technote* is a web-native single page document that enables rapid technical communication within and across teams.
+```
+
+## Introduction
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin facilisis pharetra neque, at semper nulla mattis auctor. Proin semper mollis enim eget interdum. Mauris eleifend eget diam vitae bibendum. Praesent ut aliquet odio, sodales imperdiet nisi. Nam interdum imperdiet tortor sed fringilla. Maecenas efficitur mi sodales nulla commodo rutrum. Ut ornare diam quam, sed commodo turpis aliquam et. In nec enim consequat, suscipit tortor sit amet, luctus ante. Integer dictum augue diam, non pulvinar massa euismod in. Morbi viverra condimentum auctor. Nullam et metus mauris. Cras risus ex, porta sit amet nibh et, dapibus auctor leo.
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin facilisis pharetra neque, at semper nulla mattis auctor. Proin semper mollis enim eget interdum. Mauris eleifend eget diam vitae bibendum. Praesent ut aliquet odio, sodales imperdiet nisi. Nam interdum imperdiet tortor sed fringilla. Maecenas efficitur mi sodales nulla commodo rutrum. Ut ornare diam quam, sed commodo turpis aliquam et. In nec enim consequat, suscipit tortor sit amet, luctus ante. Integer dictum augue diam, non pulvinar massa euismod in. Morbi viverra condimentum auctor. Nullam et metus mauris. Cras risus ex, porta sit amet nibh et, dapibus auctor leo.
+
+A parenthetical citation {cite:p}`2017arXiv170309824V`. And a textual citation {cite:t}`2017arXiv170309824V`.
+
+## Method
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin facilisis pharetra neque, at semper nulla mattis auctor. Proin semper mollis enim eget interdum. Mauris eleifend eget diam vitae bibendum. Praesent ut aliquet odio, sodales imperdiet nisi. Nam interdum imperdiet tortor sed fringilla. Maecenas efficitur mi sodales nulla commodo rutrum. Ut ornare diam quam, sed commodo turpis aliquam et. In nec enim consequat, suscipit tortor sit amet, luctus ante. Integer dictum augue diam, non pulvinar massa euismod in. Morbi viverra condimentum auctor. Nullam et metus mauris. Cras risus ex, porta sit amet nibh et, dapibus auctor leo.
+
+A list:
+
+- First item
+- Second item
+- Third item
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin facilisis pharetra neque, at semper nulla mattis auctor. Proin semper mollis enim eget interdum. Mauris eleifend eget diam vitae bibendum. Praesent ut aliquet odio, sodales imperdiet nisi. Nam interdum imperdiet tortor sed fringilla. Maecenas efficitur mi sodales nulla commodo rutrum. Ut ornare diam quam, sed commodo turpis aliquam et. In nec enim consequat, suscipit tortor sit amet, luctus ante. Integer dictum augue diam, non pulvinar massa euismod in. Morbi viverra condimentum auctor. Nullam et metus mauris. Cras risus ex, porta sit amet nibh et, dapibus auctor leo.
+
+```{code-block} python
+:caption: hello.py
+
+print("Hello world")
+```
+
+## Results
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin facilisis pharetra neque, at semper nulla mattis auctor. Proin semper mollis enim eget interdum. Mauris eleifend eget diam vitae bibendum. Praesent ut aliquet odio, sodales imperdiet nisi. Nam interdum imperdiet tortor sed fringilla. Maecenas efficitur mi sodales nulla commodo rutrum. Ut ornare diam quam, sed commodo turpis aliquam et. In nec enim consequat, suscipit tortor sit amet, luctus ante. Integer dictum augue diam, non pulvinar massa euismod in. Morbi viverra condimentum auctor. Nullam et metus mauris. Cras risus ex, porta sit amet nibh et, dapibus auctor leo.
+
+### Subsection
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin facilisis pharetra neque, at semper nulla mattis auctor. Proin semper mollis enim eget interdum. Mauris eleifend eget diam vitae bibendum. Praesent ut aliquet odio, sodales imperdiet nisi. Nam interdum imperdiet tortor sed fringilla. Maecenas efficitur mi sodales nulla commodo rutrum. Ut ornare diam quam, sed commodo turpis aliquam et. In nec enim consequat, suscipit tortor sit amet, luctus ante. Integer dictum augue diam, non pulvinar massa euismod in. Morbi viverra condimentum auctor. Nullam et metus mauris. Cras risus ex, porta sit amet nibh et, dapibus auctor leo.
+
+#### Subsubsection
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin facilisis pharetra neque, at semper nulla mattis auctor. Proin semper mollis enim eget interdum. Mauris eleifend eget diam vitae bibendum. Praesent ut aliquet odio, sodales imperdiet nisi. Nam interdum imperdiet tortor sed fringilla. Maecenas efficitur mi sodales nulla commodo rutrum. Ut ornare diam quam, sed commodo turpis aliquam et. In nec enim consequat, suscipit tortor sit amet, luctus ante. Integer dictum augue diam, non pulvinar massa euismod in. Morbi viverra condimentum auctor. Nullam et metus mauris. Cras risus ex, porta sit amet nibh et, dapibus auctor leo.
+
+## Analysis
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin facilisis pharetra neque, at semper nulla mattis auctor. Proin semper mollis enim eget interdum. Mauris eleifend eget diam vitae bibendum. Praesent ut aliquet odio, sodales imperdiet nisi. Nam interdum imperdiet tortor sed fringilla. Maecenas efficitur mi sodales nulla commodo rutrum. Ut ornare diam quam, sed commodo turpis aliquam et. In nec enim consequat, suscipit tortor sit amet, luctus ante. Integer dictum augue diam, non pulvinar massa euismod in. Morbi viverra condimentum auctor. Nullam et metus mauris. Cras risus ex, porta sit amet nibh et, dapibus auctor leo.
+
+```{prompt} bash
+git add index.rst
+```
+
+Some following text.
+
+```{mermaid}
+graph TD
+   A[Square Rect] -- Link text --> B((Circle))
+   A --> C(Round Rect)
+   B --> D{Rhombus}
+   C --> D
+```
+
+```{diagrams} diagram.py
+```
+
+## Conclusion
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin facilisis pharetra neque, at semper nulla mattis auctor. Proin semper mollis enim eget interdum. Mauris eleifend eget diam vitae bibendum. Praesent ut aliquet odio, sodales imperdiet nisi. Nam interdum imperdiet tortor sed fringilla. Maecenas efficitur mi sodales nulla commodo rutrum. Ut ornare diam quam, sed commodo turpis aliquam et. In nec enim consequat, suscipit tortor sit amet, luctus ante. Integer dictum augue diam, non pulvinar massa euismod in. Morbi viverra condimentum auctor. Nullam et metus mauris. Cras risus ex, porta sit amet nibh et, dapibus auctor leo.
+
+## References
+
+```{bibliography}
+```

demo/md-technote/technote.toml

@@ -0,0 +1,25 @@
+[technote]
+id = "SQR-000"
+series_id = "SQR"
+canonical_url = "https://sqr-000.lsst.io"
+github_url = "https://github.com/lsst-sqre/sqr-000"
+github_default_branch = "master"
+date_created = 2015-11-18
+date_updated = 2015-11-23
+version = "1.0.0"
+
+[[technote.authors]]
+name.given = "Jonathan"
+name.family = "Sick"
+orcid = "https://orcid.org/0000-0003-3001-676X"
+affiliations = [
+    { name = "Rubin Observatory", ror = "https://ror.org/048g3cy84" }
+]
+
+[[technote.authors]]
+name.given = "Frossie"
+name.family = "Economou"
+
+[[technote.authors]]
+name.given = "Russ"
+name.family = "Allbery"

src/documenteer/conf/technote.py

@@ -43,6 +43,12 @@
     ]
 )
 
+# The source file suffixes for .md and .ipynb are automatically managed by
+# myst-nb.
+source_suffix = {
+    ".rst": "restructuredtext",
+}
+
 html_static_path: list[str] = [
     get_asset_path("rubin-favicon-transparent-32px.png"),
     get_asset_path("rubin-favicon.svg"),

tox.ini

@@ -84,5 +84,7 @@ allowlist_externals =
 commands =
     rm -rf demo/rst-technote/_build
     sphinx-build --keep-going -n -W -T -b html -d {envtmpdir}/doctrees demo/rst-technote demo/rst-technote/_build/html
+    rm -rf demo/md-technote/_build
+    sphinx-build --keep-going -n -W -T -b html -d {envtmpdir}/doctrees demo/md-technote demo/md-technote/_build/html
     rm -rf demo/ipynb-technote/_build
     sphinx-build --keep-going -n -W -T -b html -d {envtmpdir}/doctrees demo/ipynb-technote demo/ipynb-technote/_build/html