diff --git a/.github/workflows/ci-cron.yaml b/.github/workflows/ci-cron.yaml index 6d59de8..7bba475 100644 --- a/.github/workflows/ci-cron.yaml +++ b/.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: diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index bfecc8a..b922487 100644 --- a/.github/workflows/ci.yaml +++ b/.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 diff --git a/CHANGELOG.md b/CHANGELOG.md index 236ff2f..fe5aa27 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/demo/md-technote/.gitignore b/demo/md-technote/.gitignore new file mode 100644 index 0000000..1835cfc --- /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 0000000..f7bdab8 --- /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 0000000..fddf299 --- /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 0000000..c193c63 --- /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 0000000..526accb --- /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 0000000..a93af9b --- /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/src/documenteer/conf/technote.py b/src/documenteer/conf/technote.py index 711302d..743441f 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"), diff --git a/tox.ini b/tox.ini index f0fc9ee..5e7190d 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