Merge pull request #202 from lsst-sqre:tickets/DM-41905

DM-41905: Add defalut Sphinx extensions for technotes

changelog.d/20231129_140754_jsick_DM_41905.md

@@ -0,0 +1,21 @@
+<!-- Delete the sections that don't apply -->
+
+### Backwards-incompatible changes
+
+-
+
+### New features
+
+- Add new default Sphinx extensions for technotes:
+
+  - sphinx-prompt
+  - sphinxcontrib-mermaid
+  - sphinx-diagrams
+
+### Bug fixes
+
+-
+
+### Other changes
+
+-

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")
+    )

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
 ==========
 

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
 

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 = [

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:
 

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 </sphinx-extensions/jira-reference>`
+   This extension provides roles for linking to Jira issues.
+
+:doc:`documenteer.ext.lsstdocushare </sphinx-extensions/docushare-reference>`
+   This extension provides roles for linking to Rubin Observatory documents based on their handle.
+
+:doc:`documenteer.ext.remotecodeblock </sphinx-extensions/remote-code-block>`
+   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 </sphinx-extensions/lsst-pybtex-style>`
+   This extension works with the `sphinxcontrib-bibtex`_ extension to handle the BibTeX entires in https://github.com/lsst/lsst-texmf.
+
+:doc:`documenteer.ext.githubbibcache </sphinx-extensions/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 <toml-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"

docs/technotes/index.rst

@@ -19,6 +19,7 @@ Documenteer provides centralized configuration and tooling for technotes.
 
    document-status
    configuration
+   extensions
 
 .. seealso::
 

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::

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]

src/documenteer/conf/technote.py

@@ -24,6 +24,9 @@
         "documenteer.ext.bibtex",
         "documenteer.ext.githubbibcache",
         "sphinxcontrib.bibtex",
+        "sphinx_diagrams",
+        "sphinxcontrib.mermaid",
+        "sphinx_prompt",
     ]
 )