From 53369249897b7ed33655c3f5ba6b80c0e56711e9 Mon Sep 17 00:00:00 2001 From: Jonathan Sick Date: Tue, 2 Apr 2024 11:36:02 -0400 Subject: [PATCH 1/5] Add demo markdown technote This will help us catch configuration issues for Markdown technotes, like we do for reStructuredText and ipynb technotes. --- demo/md-technote/.gitignore | 2 + demo/md-technote/Makefile | 3 ++ demo/md-technote/conf.py | 1 + demo/md-technote/diagram.py | 14 +++++++ demo/md-technote/index.md | 73 ++++++++++++++++++++++++++++++++++ demo/md-technote/technote.toml | 25 ++++++++++++ tox.ini | 2 + 7 files changed, 120 insertions(+) create mode 100644 demo/md-technote/.gitignore create mode 100644 demo/md-technote/Makefile create mode 100644 demo/md-technote/conf.py create mode 100644 demo/md-technote/diagram.py create mode 100644 demo/md-technote/index.md create mode 100644 demo/md-technote/technote.toml diff --git a/demo/md-technote/.gitignore b/demo/md-technote/.gitignore new file mode 100644 index 00000000..1835cfcf --- /dev/null +++ b/demo/md-technote/.gitignore @@ -0,0 +1,2 @@ +_build +.technote diff --git a/demo/md-technote/Makefile b/demo/md-technote/Makefile new file mode 100644 index 00000000..f7bdab8a --- /dev/null +++ b/demo/md-technote/Makefile @@ -0,0 +1,3 @@ +.PHONY: +clean: + rm -rf _build diff --git a/demo/md-technote/conf.py b/demo/md-technote/conf.py new file mode 100644 index 00000000..fddf299c --- /dev/null +++ b/demo/md-technote/conf.py @@ -0,0 +1 @@ +from documenteer.conf.technote import * # noqa F401 F403 diff --git a/demo/md-technote/diagram.py b/demo/md-technote/diagram.py new file mode 100644 index 00000000..c193c635 --- /dev/null +++ b/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") + ) diff --git a/demo/md-technote/index.md b/demo/md-technote/index.md new file mode 100644 index 00000000..526accbf --- /dev/null +++ b/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} +``` diff --git a/demo/md-technote/technote.toml b/demo/md-technote/technote.toml new file mode 100644 index 00000000..a93af9be --- /dev/null +++ b/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" diff --git a/tox.ini b/tox.ini index f0fc9eee..5e7190d3 100644 --- a/tox.ini +++ b/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 From 2f3acde7ae980aa4787354808c6128bc13e59b5f Mon Sep 17 00:00:00 2001 From: Jonathan Sick Date: Tue, 2 Apr 2024 12:16:08 -0400 Subject: [PATCH 2/5] Allow MyST-NB to config source parers for technote By adding a `source_suffix` configuration listing only the rst suffix allows MyST-NB to add the necessary source parsers for both ipynb and md files. This resolves the "Source parser for markdown not registered" error. --- changelog.d/20240402_121001_jsick_DM_43617.md | 3 +++ src/documenteer/conf/technote.py | 6 ++++++ 2 files changed, 9 insertions(+) create mode 100644 changelog.d/20240402_121001_jsick_DM_43617.md diff --git a/changelog.d/20240402_121001_jsick_DM_43617.md b/changelog.d/20240402_121001_jsick_DM_43617.md new file mode 100644 index 00000000..aa686352 --- /dev/null +++ b/changelog.d/20240402_121001_jsick_DM_43617.md @@ -0,0 +1,3 @@ +### 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. diff --git a/src/documenteer/conf/technote.py b/src/documenteer/conf/technote.py index 711302da..743441fd 100644 --- a/src/documenteer/conf/technote.py +++ b/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"), From 29dab6bcb3aa3d691a1ecbae39c08f11345bab37 Mon Sep 17 00:00:00 2001 From: Jonathan Sick Date: Tue, 2 Apr 2024 12:19:34 -0400 Subject: [PATCH 3/5] Prepare change log for 1.2.1 --- CHANGELOG.md | 7 +++++++ changelog.d/20240402_121001_jsick_DM_43617.md | 3 --- 2 files changed, 7 insertions(+), 3 deletions(-) delete mode 100644 changelog.d/20240402_121001_jsick_DM_43617.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 236ff2f7..fe5aa27b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,13 @@ + +## 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. + ## 1.2.0 (2024-03-26) diff --git a/changelog.d/20240402_121001_jsick_DM_43617.md b/changelog.d/20240402_121001_jsick_DM_43617.md deleted file mode 100644 index aa686352..00000000 --- a/changelog.d/20240402_121001_jsick_DM_43617.md +++ /dev/null @@ -1,3 +0,0 @@ -### 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. From 454eb2bd4c92d21fe66afef02cf2fa13c7025329 Mon Sep 17 00:00:00 2001 From: Jonathan Sick Date: Tue, 2 Apr 2024 12:32:24 -0400 Subject: [PATCH 4/5] Run demo tox env in CI This will create demo technotes. --- .github/workflows/ci-cron.yaml | 2 +- .github/workflows/ci.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci-cron.yaml b/.github/workflows/ci-cron.yaml index 6d59de83..92cc85e8 100644 --- a/.github/workflows/ci-cron.yaml +++ b/.github/workflows/ci-cron.yaml @@ -45,7 +45,7 @@ jobs: 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: diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index bfecc8a8..001e9af8 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -65,7 +65,7 @@ jobs: 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 From 95d5edaa1e13e88217a3deb6faa694fa8a6ff9a7 Mon Sep 17 00:00:00 2001 From: Jonathan Sick Date: Tue, 2 Apr 2024 12:36:43 -0400 Subject: [PATCH 5/5] Install graphviz for testing demos Required by diagrams. --- .github/workflows/ci-cron.yaml | 5 +++++ .github/workflows/ci.yaml | 5 +++++ 2 files changed, 10 insertions(+) diff --git a/.github/workflows/ci-cron.yaml b/.github/workflows/ci-cron.yaml index 92cc85e8..7bba4751 100644 --- a/.github/workflows/ci-cron.yaml +++ b/.github/workflows/ci-cron.yaml @@ -41,6 +41,11 @@ 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: diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 001e9af8..b9224878 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -61,6 +61,11 @@ 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: