From ece778cc7bc936f871556c41decdb9aca329e46c Mon Sep 17 00:00:00 2001 From: Jonathan Sick Date: Tue, 18 Jun 2024 16:12:35 -0400 Subject: [PATCH 1/5] Update technote to 0.9 This is to test out the new grid layout for technotes that enables wide content to bleed to the right whitespace. --- changelog.d/20240711_142152_jsick_DM_44542.md | 3 +++ pyproject.toml | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) create mode 100644 changelog.d/20240711_142152_jsick_DM_44542.md diff --git a/changelog.d/20240711_142152_jsick_DM_44542.md b/changelog.d/20240711_142152_jsick_DM_44542.md new file mode 100644 index 00000000..826f69b7 --- /dev/null +++ b/changelog.d/20240711_142152_jsick_DM_44542.md @@ -0,0 +1,3 @@ +### 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). diff --git a/pyproject.toml b/pyproject.toml index b27ced01..005e0160 100644 --- 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", From 68ee1462e93c9bd5e62f6c43a39054ef34c45700 Mon Sep 17 00:00:00 2001 From: Jonathan Sick Date: Thu, 20 Jun 2024 12:11:51 -0400 Subject: [PATCH 2/5] Drop header margin tweaks These are now part of technote 0.9's CSS. --- src/assets/rubin-technote/styles/_hacks.scss | 16 +++------------- 1 file changed, 3 insertions(+), 13 deletions(-) diff --git a/src/assets/rubin-technote/styles/_hacks.scss b/src/assets/rubin-technote/styles/_hacks.scss index 0527757b..ba241d29 100644 --- a/src/assets/rubin-technote/styles/_hacks.scss +++ b/src/assets/rubin-technote/styles/_hacks.scss @@ -4,20 +4,10 @@ * their proper module either in documenteer or in the parent technote theme. */ -@media (max-width: 76rem) { - // Reduce the margin-bottom on headings in mobile views - h1, - h2, - h3, - h4, - h5, - h6 { - margin-bottom: 0.5em; - } -} - /* - * Border specififcally for prompts, which act differently than code blocks. + * Border specifically for prompt-type code blocks, which act differently + * than code blocks. The prompt extension is used specially by Documenteer + * technotes. */ .highlight-default .highlight { border: var(--tn-sphinx-code-block-border-thickness) solid From 6252fc7343b3af8a9bd368fd61e65e4f62631cc2 Mon Sep 17 00:00:00 2001 From: Jonathan Sick Date: Thu, 11 Jul 2024 12:14:38 -0400 Subject: [PATCH 3/5] Extend test cases for markdown technote --- demo/md-technote/index.md | 166 +++++++++++++++++++++++++++++++++----- 1 file changed, 148 insertions(+), 18 deletions(-) diff --git a/demo/md-technote/index.md b/demo/md-technote/index.md index 612281ab..a1a09353 100644 --- 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 ``` From 7a4b6184c4401ae1523e922cf18e5f03483a092e Mon Sep 17 00:00:00 2001 From: Jonathan Sick Date: Thu, 11 Jul 2024 15:58:08 -0400 Subject: [PATCH 4/5] Add documentation on using technote-wide-content --- docs/technotes/index.rst | 6 ++ docs/technotes/wide-content.rst | 145 ++++++++++++++++++++++++++++++++ 2 files changed, 151 insertions(+) create mode 100644 docs/technotes/wide-content.rst diff --git a/docs/technotes/index.rst b/docs/technotes/index.rst index bb9ef5ec..7635f411 100644 --- 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 new file mode 100644 index 00000000..c0961402 --- /dev/null +++ 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. + ``` From ae53608456db0bca113ba5b1310d4d9c27e8b092 Mon Sep 17 00:00:00 2001 From: Jonathan Sick Date: Thu, 11 Jul 2024 16:22:39 -0400 Subject: [PATCH 5/5] Update change log for 1.4.0 release --- CHANGELOG.md | 7 +++++++ changelog.d/20240711_142152_jsick_DM_44542.md | 3 --- 2 files changed, 7 insertions(+), 3 deletions(-) delete mode 100644 changelog.d/20240711_142152_jsick_DM_44542.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 5a2d59d5..8ab4a7cd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,13 @@ + +## 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). + ## 1.3.0 (2024-05-03) diff --git a/changelog.d/20240711_142152_jsick_DM_44542.md b/changelog.d/20240711_142152_jsick_DM_44542.md deleted file mode 100644 index 826f69b7..00000000 --- a/changelog.d/20240711_142152_jsick_DM_44542.md +++ /dev/null @@ -1,3 +0,0 @@ -### 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).