diff --git a/CHANGELOG.md b/CHANGELOG.md index 5a2d59d..8ab4a7c 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/demo/md-technote/index.md b/demo/md-technote/index.md index 612281a..a1a0935 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 ``` diff --git a/docs/technotes/index.rst b/docs/technotes/index.rst index bb9ef5e..7635f41 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 0000000..c096140 --- /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. + ``` diff --git a/pyproject.toml b/pyproject.toml index b27ced0..005e016 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", diff --git a/src/assets/rubin-technote/styles/_hacks.scss b/src/assets/rubin-technote/styles/_hacks.scss index 0527757..ba241d2 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