From 77708895543eb1b6d535bdcdc5a80b8ffff711e5 Mon Sep 17 00:00:00 2001 From: Jonathan Sick Date: Wed, 29 Nov 2023 14:00:27 -0500 Subject: [PATCH 1/3] Add documentation for extensions in technotes - Document the default extensions - Document how to add new extensions with technote.toml - Drop old docs for adding an extension purely based on conf.py. --- docs/_rst_epilog.rst | 3 + docs/documenteer.toml | 1 + docs/technotes/configuration.rst | 10 +--- docs/technotes/extensions.rst | 98 ++++++++++++++++++++++++++++++++ docs/technotes/index.rst | 1 + docs/technotes/migrate.rst | 2 +- 6 files changed, 105 insertions(+), 10 deletions(-) create mode 100644 docs/technotes/extensions.rst diff --git a/docs/_rst_epilog.rst b/docs/_rst_epilog.rst index dd823d93..0d6fd422 100644 --- a/docs/_rst_epilog.rst +++ b/docs/_rst_epilog.rst @@ -55,8 +55,11 @@ .. _sphinx_autodoc_typehints: https://github.com/tox-dev/sphinx-autodoc-typehints .. _sphinxcontrib-redoc: https://sphinxcontrib-redoc.readthedocs.io/en/stable/ .. _sphinxcontrib-bibtex: https://sphinxcontrib-bibtex.readthedocs.io/en/latest/ +.. _sphinx-prompt: https://github.com/sbrunner/sphinx-prompt .. _tox: https://tox.wiki/en/latest/ .. _Technote: https://technote.lsst.io/ +.. _`myst_parser`: https://myst-parser.readthedocs.io/en/latest/index.html +.. _sphinx.ext.intersphinx: https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html .. Internal links diff --git a/docs/documenteer.toml b/docs/documenteer.toml index 896f4486..5135df8a 100644 --- a/docs/documenteer.toml +++ b/docs/documenteer.toml @@ -38,6 +38,7 @@ developer = "https://developer.lsst.io/" pybtex = "https://docs.pybtex.org/" sphinx = "https://www.sphinx-doc.org/en/master/" sphinxcontrib-bibtex = "https://sphinxcontrib-bibtex.readthedocs.io/en/latest/" +technote = "https://technote.lsst.io/" [sphinx.linkcheck] ignore = [ diff --git a/docs/technotes/configuration.rst b/docs/technotes/configuration.rst index 0c5a9b48..20b6fbcd 100644 --- a/docs/technotes/configuration.rst +++ b/docs/technotes/configuration.rst @@ -55,15 +55,7 @@ Adding a Sphinx extension ------------------------- You can add additional `Sphinx extensions`_ to your Sphinx build to make use of custom reStructuredText directives and roles. -To add a new extension, append to the ``extensions`` list: - -.. code-block:: python - - from documenteer.conf.technote import * - - extensions.extend(["sphinx-click"]) - -Remember that if an additional package needs to be installed, add that dependency to the technote's :file:`requirements.txt` file. +See :ref:`technote-adding-extensions`. .. _technote-conf-source: diff --git a/docs/technotes/extensions.rst b/docs/technotes/extensions.rst new file mode 100644 index 00000000..bce241aa --- /dev/null +++ b/docs/technotes/extensions.rst @@ -0,0 +1,98 @@ +############################## +Sphinx extensions in technotes +############################## + +Technotes include Sphinx extensions that provide additional features, like diagrams-as-code. +This page explains what extensions are included by default in Rubin technotes, and how to add additional extensions to your own technote as needed. + +.. _technote-default-extensions: + +Default extensions +================== + +These extensions are included and pre-configured in all technotes: + +:doc:`documenteer.ext.jira ` + This extension provides roles for linking to Jira issues. + +:doc:`documenteer.ext.lsstdocushare ` + This extension provides roles for linking to Rubin Observatory documents based on their handle. + +:doc:`documenteer.ext.remotecodeblock ` + This extension allows you to include a literal code block where the source for that code block is available at an web URL. + +:doc:`documenteer.ext.bibtex ` + This extension works with the `sphinxcontrib-bibtex`_ extension to handle the BibTeX entires in https://github.com/lsst/lsst-texmf. + +:doc:`documenteer.ext.githubbibcache ` + This extension automatically downloads and caches the BibTeX files from https://github.com/lsst/lsst-texmf, for use with the `sphinxcontrib-bibtex`_ extension. + +`myst_parser`_ + This extension allows you to use the MyST_ markup language (i.e., Markdown) in your technote. + +`sphinx.ext.intersphinx`_ + This extension allows you to link to other Sphinx projects, including other Rubin technotes and user guides and many open-source projects like Astropy and Numpy. + +`sphinxcontrib-bibtex`_ + This extension allow you to include a BibTeX-based bibliography in your technote. + +`sphinx-prompt`_ + Sphinx-prompt lets you add a prompt to code blocks. + This is useful for showing what a user might type at an interactive terminal. + +`sphinxcontrib-mermaid`_ + Mermaid is a diagrams-as-code tool that allows you to create flowcharts, sequence diagrams, entity relationship diagrams, and more. + See the Mermaid_ documentation for more information, and see the `sphinxcontrib-mermaid`_ documentation for Sphinx-specific usage. + +`sphinx-diagrams`_ + The Diagrams extension allows you to make architectural diagrams from code. + This extension is particularly useful for describing Kubernetes application deployments. + +.. _technote-adding-extensions: + +Adding additional extensions +============================ + +If you know of a Sphinx extension that you would like to use with your technote, you can add it yourself. +Here are the steps, using sphinxcontrib-mermaid_ as an example (this is already included in all technotes): + +1. Add the extension's Python package to :file:`requirements.txt` in the technote's repository. + This is the extension's PyPI package name, since technotes use pip to install build dependencies. + + .. code-block:: text + :caption: requirements.txt + :emphasize-lines: 2 + + documenteer[technote] + sphinxcontrib-mermaid + +2. Add the extension to the :external+technote:ref:`technote.sphinx.extensions ` array in :file:`technote.toml`. + Either append to the existing array, or create a new array if it doesn't exist in the TOML file yet. + + .. code-block:: toml + :caption: technote.toml + :emphasize-lines: 2 + + [technote.sphinx] + extensions = ["sphinxcontrib.mermaid"] + + .. tip:: + + The extension name is the Python package name, not the PyPI package name. + Look at the extension's installation documentation for the ``extensions`` variable to find the Python package name. + + .. note:: + + User-defined extensions are always installed *in addition to* the default extensions. + You don't need to repeat the default extensions here. + +3. If the extension has configurations, you can set those in the :file:`conf.py` file. + + .. code-block:: python + :caption: conf.py + :emphasize-lines: 3,4 + + from documenteer.conf.technote import * # noqa: F401, F403 + + # -- Options for sphinxcontrib-mermaid ------------------------------------- + mermaid_version = "8.9.2" diff --git a/docs/technotes/index.rst b/docs/technotes/index.rst index 743de212..0ac233c0 100644 --- a/docs/technotes/index.rst +++ b/docs/technotes/index.rst @@ -19,6 +19,7 @@ Documenteer provides centralized configuration and tooling for technotes. document-status configuration + extensions .. seealso:: diff --git a/docs/technotes/migrate.rst b/docs/technotes/migrate.rst index d426186a..c5fdceb5 100644 --- a/docs/technotes/migrate.rst +++ b/docs/technotes/migrate.rst @@ -168,7 +168,7 @@ The new technote format uses an ``abstract`` directive to mark up the abstract/s Simplify the reference section ------------------------------ -If your technote makes references to other documents with roles like :rst:dir:`cite`, you'll need a reference section to display the bibliography. +If your technote makes references to other documents with roles like :external+sphinxcontrib-bibtex:rst:role:`cite`, you'll need a reference section to display the bibliography. In the new technote format, this section is simplified: .. tab-set:: From ff535aa789e1cbbf54816d8c0a3dafe354c26819 Mon Sep 17 00:00:00 2001 From: Jonathan Sick Date: Wed, 29 Nov 2023 14:10:50 -0500 Subject: [PATCH 2/3] Add more default extensions for technotes Add: - sphinx-prompt - sphinxcontrib-mermaid - sphinx-diagrams --- changelog.d/20231129_140754_jsick_DM_41905.md | 21 +++++++++++++++++++ pyproject.toml | 2 ++ src/documenteer/conf/technote.py | 3 +++ 3 files changed, 26 insertions(+) create mode 100644 changelog.d/20231129_140754_jsick_DM_41905.md diff --git a/changelog.d/20231129_140754_jsick_DM_41905.md b/changelog.d/20231129_140754_jsick_DM_41905.md new file mode 100644 index 00000000..c8f0ec44 --- /dev/null +++ b/changelog.d/20231129_140754_jsick_DM_41905.md @@ -0,0 +1,21 @@ + + +### Backwards-incompatible changes + +- + +### New features + +- Add new default Sphinx extensions for technotes: + + - sphinx-prompt + - sphinxcontrib-mermaid + - sphinx-diagrams + +### Bug fixes + +- + +### Other changes + +- diff --git a/pyproject.toml b/pyproject.toml index a8f20a47..5807150a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -98,6 +98,8 @@ technote = [ # Theme and extensions for technotes "technote>=0.5.0,<0.6.0", "sphinx-prompt", + "sphinxcontrib-mermaid", + "sphinx-diagrams", ] [project.urls] diff --git a/src/documenteer/conf/technote.py b/src/documenteer/conf/technote.py index 8943b81d..d758f68b 100644 --- a/src/documenteer/conf/technote.py +++ b/src/documenteer/conf/technote.py @@ -24,6 +24,9 @@ "documenteer.ext.bibtex", "documenteer.ext.githubbibcache", "sphinxcontrib.bibtex", + "sphinx_diagrams", + "sphinxcontrib.mermaid", + "sphinx_prompt", ] ) From cb16517e2027b3d30959467c794a84fa92ebda8c Mon Sep 17 00:00:00 2001 From: Jonathan Sick Date: Wed, 29 Nov 2023 16:50:31 -0500 Subject: [PATCH 3/3] Add demo for additional sphinx extensions --- demo/rst-technote/diagram.py | 14 ++++++++++++++ demo/rst-technote/index.rst | 14 ++++++++++++++ 2 files changed, 28 insertions(+) create mode 100644 demo/rst-technote/diagram.py diff --git a/demo/rst-technote/diagram.py b/demo/rst-technote/diagram.py new file mode 100644 index 00000000..c193c635 --- /dev/null +++ b/demo/rst-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/rst-technote/index.rst b/demo/rst-technote/index.rst index fbd761ff..2058dd43 100644 --- a/demo/rst-technote/index.rst +++ b/demo/rst-technote/index.rst @@ -56,6 +56,20 @@ 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 + +.. mermaid:: + + graph TD + A[Square Rect] -- Link text --> B((Circle)) + A --> C(Round Rect) + B --> D{Rhombus} + C --> D + +.. diagrams:: diagram.py + Conclusion ==========