Merge pull request #228 from lsst-sqre/tickets/DM-44542

DM-44542: Adopt technote 0.9 and wide content utility class
lsst-sqre · Jul 11, 2024 · 8d2bb24 · 8d2bb24
2 parents 2ca5819 + ae53608
commit 8d2bb24
Show file tree

Hide file tree

Showing 6 changed files with 310 additions and 32 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,13 @@
 
 <!-- scriv-insert-here -->
 
+<a id='changelog-1.4.0'></a>
+## 1.4.0 (2024-07-11)
+
+### New features
+
+- Update to technote 0.9.0. This new version of the technote theme features a two column layout that allows wide content, such as tables, code blocks, and figures, to span the full width of the page (bleeding beyond the text column).
+
 <a id='changelog-1.3.0'></a>
 ## 1.3.0 (2024-05-03)
 

diff --git a/demo/md-technote/index.md b/demo/md-technote/index.md
@@ -12,45 +12,170 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin facilisis pharetr
 
 A parenthetical citation {cite:p}`SQR-083`. And a textual citation {cite:t}`SQR-083`.
 
-## Method
+This is `inline code`.
 
-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:
+## Images and figures
 
-- First item
-- Second item
-- Third item
+A figure with a caption:
 
-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.
+```{figure} https://placehold.co/1200x400
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed euismod, nisl quis molestie ultricies, nunc nisl aliquet nunc, quis aliquam nisl nunc eu nisl.
+```
+
+### Wide figures
+
+A figure marked with the `technote-wide-content` class applied as a `figclass` option:
+
+```{figure} https://placehold.co/1200x400
+:figclass: technote-wide-content
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed euismod, nisl quis molestie ultricies, nunc nisl aliquet nunc, quis aliquam nisl nunc eu nisl.
+```
+
+### Tables
+
+A table:
+
+```{list-table}
+:header-rows: 1
+
+* - Column 1
+  - Column 2
+  - Column 3
+* - Row 1
+  - 1
+  - 1
+* - Row 2
+  - 2
+  - 2
+* - Row 3
+  - 3
+  - 3
+```
+
+A table marked with the `technote-wide-content` class:
+
+```{rst-class} technote-wide-content
+```
+
+```{list-table}
+:header-rows: 1
+
+* - Column 1
+  - Column 2
+  - Column 3
+  - Column 4
+  - Column 5
+  - Column 6
+  - Column 7
+* - Row 1
+  - lorem ipsum dolor sit amet consectetur adipiscing elit
+  - lorem ipsum dolor
+  - lorem ipsum dolor
+  - 5
+  - 6
+  - Lorem ipsum
+* - Row 2
+  - 6
+  - 7
+  - 8
+  - 9
+  - 10
+  - Lorem ipsum
+```
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed euismod, nisl quis molestie ultricies, nunc nisl aliquet nunc, quis aliquam nisl nunc eu nisl.
+
+### Code blocks
+
+A regular code block:
+
+```{code-block} python
+print("Hello, world!")
+```
+
+And with a caption:
 
 ```{code-block} python
-:caption: hello.py
+:caption: A code block with a caption
 
-print("Hello world")
+print("Hello, world!")
 ```
 
-## Results
+A wide code block without a caption:
 
-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.
+```{rst-class} technote-wide-content
+```
 
-### Subsection
+```{code-block} python
+print("Hello, world! This is a code block. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed euismod, nisl quis molestie ultricies, nunc nisl aliquet nunc, quis aliquam nisl nunc eu nisl.")
+```
 
-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 wide code block with a caption where the class is set externally:
 
-#### Subsubsection
+```{rst-class} technote-wide-content
+```
 
-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: A wide code block. This is a long caption. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed euismod, nisl quis molestie ultricies, nunc nisl aliquet nunc, quis aliquam nisl nunc eu nisl.
 
-## Analysis
+print("Hello, world! This is a code block. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed euismod, nisl quis molestie ultricies, nunc nisl aliquet nunc, quis aliquam nisl nunc eu nisl.")
+```
 
-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 code prompt:
 
 ```{prompt} bash
 git add index.rst
 ```
 
-Some following text.
+## Admonitions
+
+An admonition:
+
+```{note}
+This is a note. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed euismod, nisl quis molestie ultricies, nunc nisl aliquet nunc, quis aliquam nisl nunc eu nisl.
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed euismod, nisl quis molestie ultricies, nunc nisl aliquet nunc, quis aliquam nisl nunc eu nisl.
+```
+
+## Lists
+
+A bulleted list:
+
+- Item 1
+- Item 2
+- Item 3
+
+A numbered list:
+
+1. Item 1
+2. Item 2
+3. Item 3
+
+A bulleted list with a nested numbered list:
+
+- Item 1
+  1. Item 1.1
+  2. Item 1.2
+- Item 2
+- Item 3
+
+A definition list:
+
+term 1
+  Definition 1
+term 2
+  Definition 2 Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed euismod, nisl quis molestie ultricies, nunc nisl aliquet nunc, quis aliquam nisl nunc eu nisl.
+
+## Links
+
+A link to [Rubin Observatory](https://www.rubinobservatory.org).
+
+## Analysis
+
+A flowchart made with Mermaid:
 
 ```{mermaid}
 graph TD
@@ -60,6 +185,11 @@ graph TD
    C --> D
 ```
 
+A diagram:
+
+```{rst-class} technote-wide-content
+```
+
 ```{diagrams} diagram.py
 ```
 

diff --git a/docs/technotes/index.rst b/docs/technotes/index.rst
@@ -24,6 +24,12 @@ Documenteer provides centralized configuration and tooling for technotes.
    author-metadata
    document-status
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Content & design
+
+   wide-content
+
 .. toctree::
    :maxdepth: 2
    :caption: Sphinx configuration

diff --git a/docs/technotes/wide-content.rst b/docs/technotes/wide-content.rst
@@ -0,0 +1,145 @@
+############################################################
+Accommodating wide content (tables, code blocks, and images)
+############################################################
+
+Technotes use a narrow content column to improve readability.
+However, some content types need to more horizontal space.
+This page explains how to use the ``technote-wide-content`` CSS utility class to let content span the full width of the page.
+
+Tables and code blocks
+======================
+
+To allow a table or code block to span the available horizontal space on a page, you can preceed it with the ``technote-wide-content`` class in a ``rst-class`` directive.
+The ``rst-class`` directive is not part of the table or code-block's directive, but is a separate preceeding directive that applies the ``technote-wide-content`` class to the following content.
+
+Tables
+------
+
+.. tab-set::
+
+   .. tab-item:: reStructuredText
+      :sync: rst
+
+      .. code-block:: rst
+
+         .. rst-class:: technote-wide-content
+
+         +-----------------+-----------------+
+         | Header 1        | Header 2        |
+         +=================+=================+
+         | Row 1, Column 1 | Row 1, Column 2 |
+         +-----------------+-----------------+
+         | Row 2, Column 1 | Row 2, Column 2 |
+         +-----------------+-----------------+
+
+   .. tab-item:: markdown
+        :sync: md
+
+        .. code-block:: md
+
+           ```{rst-class} technote-wide-content
+           ```
+
+           | Header 1        | Header 2        |
+           | --------------- | --------------- |
+           | Row 1, Column 1 | Row 1, Column 2 |
+           | Row 2, Column 1 | Row 2, Column 2 |
+
+List tables
+-----------
+
+.. tab-set::
+
+   .. tab-item:: reStructuredText
+      :sync: rst
+
+      .. code-block:: rst
+
+         .. rst-class:: technote-wide-content
+
+         .. list-table::
+            :header-rows: 1
+
+            * - Header 1
+              - Header 2
+            * - Row 1, Column 1
+              - Row 1, Column 2
+            * - Row 2, Column 1
+              - Row 2, Column 2
+
+   .. tab-item:: markdown
+
+      .. code-block:: md
+
+         ```{rst-class} technote-wide-content
+         ```
+
+         ```{list-table}
+         :header-rows: 1
+
+         * - Header 1
+           - Header 2
+         * - Row 1, Column 1
+           - Row 1, Column 2
+         * - Row 2, Column 1
+           - Row 2, Column 2
+         ```
+
+Code blocks
+-----------
+
+.. tab-set::
+
+   .. tab-item:: reStructuredText
+      :sync: rst
+
+      .. code-block:: rst
+
+         .. rst-class:: technote-wide-content
+
+         .. code-block:: python
+
+            def my_function():
+                return "Hello, world!"
+
+   .. tab-item:: markdown
+      :sync: md
+
+      .. code-block:: md
+
+         ```{rst-class} technote-wide-content
+         ```
+
+         ```python
+         def my_function():
+             return "Hello, world!"
+         ```
+
+Images and figures
+==================
+
+In technotes, plots and images should be presented with the ``figure`` directive so that they can be captioned and referenced.
+Figures support a ``figclass`` option that is compatible with the ``technote-wide-content`` class, which lets you avoid using a separate ``rst-class`` directive.
+
+.. tab-set::
+
+   .. tab-item:: reStructuredText
+      :sync: rst
+
+      .. code-block:: rst
+
+         .. figure:: my-plot.png
+            :figclass: technote-wide-content
+
+            My plot.
+
+   .. tab-item:: markdown
+      :sync: md
+
+      .. code-block:: md
+
+         ```{figure} my-plot.png
+         :figclass: technote-wide-content
+
+         My plot.
+         ```
diff --git a/pyproject.toml b/pyproject.toml
@@ -103,7 +103,7 @@ pipelines = [
 ]
 technote = [
     # Theme and extensions for technotes
-    "technote>=0.8.0,<0.9.0",
+    "technote>=0.9.0,<0.10.0",
     "sphinx-prompt",
     "sphinxcontrib-mermaid",
     "sphinx-diagrams",