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

DM-44542: Two column layout

.pre-commit-config.yaml

@@ -7,24 +7,21 @@ repos:
       - id: check-toml
 
   - repo: https://github.com/pre-commit/mirrors-prettier
-    rev: v4.0.0-alpha.8
+    # prettier 4 is not compatible with pre-commit
+    rev: v3.1.0
     hooks:
       - id: prettier
 
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: v0.4.2
+    rev: v0.4.5
     hooks:
+      - id: ruff-format
       - id: ruff
         args: [--fix, --exit-non-zero-on-fix]
 
-  - repo: https://github.com/psf/black
-    rev: 24.4.2
-    hooks:
-      - id: black
-
   - repo: https://github.com/asottile/blacken-docs
     rev: 1.16.0
     hooks:
       - id: blacken-docs
-        additional_dependencies: [black==23.7.0]
+        additional_dependencies: [black==24.3.0]
         args: [-l, '79', -t, py311]

changelog.d/20240527_110205_jsick_DM_43638.md

@@ -0,0 +1,17 @@
+<!-- Delete the sections that don't apply -->
+
+### Backwards-incompatible changes
+
+- We've "vendored" sphinx-basic-ng into the Technote project itself. This is to prepare for changing the technote theme to a two column layout.
+
+### New features
+
+-
+
+### Bug fixes
+
+-
+
+### Other changes
+
+- Adopt ruff for formatting (dropping Black).

changelog.d/20240620_135505_jsick_DM_44542.md

@@ -0,0 +1,19 @@
+<!-- Delete the sections that don't apply -->
+
+### Backwards-incompatible changes
+
+-
+
+### New features
+
+- Technote now features a two-column layout. The left column contains the table of contents and metadata, while the right column contains the content. This layout allows for wide content to "bleed" into the whitespace to the right of the content column. With this change, we've essentially dropped the CSS patterns from the `sphinx-basic-ng` theme. The Technote layout is now built around CSS grid.
+
+- Wide content (such as figures, tables, and code blocks) can now extend past the content column if the author sets the `technote-wide-content` class on the content. This class is applied as a `figclass` option in figures or as a preceeding `rst-class` directive to tables and code blocks.
+
+### Bug fixes
+
+-
+
+### Other changes
+
+-

demo/md/index.md

@@ -8,9 +8,163 @@ A *technote* is a web-native single page document that enables rapid technical c
 
 Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed euismod, nisl quis molestie ultricies, nunc nisl aliquet nunc, quis aliquam nisl nunc eu nisl.
 
-Add an image with a caption:
+## Images and figures
+
+A figure with a caption:
 
 ```{figure} rubin-watermark.png
 
-The Rubin watermark.
+The Rubin watermark. 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: A code block with a caption
+
+print("Hello, world!")
+```
+
+A wide code block without a caption:
+
+```{rst-class} technote-wide-content
+```
+
+```{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.")
+```
+
+A wide code block with a caption where the class is set externally:
+
+```{rst-class} technote-wide-content
+```
+
+```{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.
+
+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.")
+```
+
+A wide code block with a caption where the class is set internally (this will not work):
+
+```{code-block} python
+:caption: A wide code block
+:class: technote-wide-content
+
+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.")
+```
+
+## 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).

pyproject.toml

@@ -88,24 +88,6 @@ exclude_lines = [
     "if TYPE_CHECKING:",
 ]
 
-[tool.black]
-line-length = 79
-target-version = ["py311"]
-exclude = '''
-/(
-    \.eggs
-  | \.git
-  | \.mypy_cache
-  | \.tox
-  | \.venv
-  | _build
-  | build
-  | dist
-)/
-'''
-# Use single-quoted strings so TOML treats the string like a Python r-string
-#  Multi-line strings are implicitly treated by black as regular expressions
-
 [tool.pytest.ini_options]
 asyncio_mode = "strict"
 python_files = ["tests/*.py", "tests/*/*.py"]

src/assets/scripts/technote.js

@@ -71,3 +71,41 @@ export function documentReady(callback) {
  * Add handlers.
  */
 documentReady(addThemeModeListener);
+
+/**
+ * Add listener for contents outline navigation button.
+ */
+function toggleContentsOutline() {
+  document
+    .querySelector('#technote-contents-toggle')
+    .classList.toggle('technote-contents-toggle--active');
+  document
+    .querySelector('.technote-outline-container')
+    .classList.toggle('technote-outline-container--visible');
+
+  const showLabel =
+    '<svg class="technote-svg-icon"><use href="#svg-octicon-three-bars-16"></svg> Contents';
+  const hideLabel =
+    '<svg class="technote-svg-icon"><use href="#svg-octicon-filled-x-16"></svg> Hide contents';
+
+  document.querySelector(
+    '#technote-contents-toggle.technote-contents-toggle--active'
+  )
+    ? (document.querySelector('#technote-contents-toggle').innerHTML =
+        hideLabel)
+    : (document.querySelector('#technote-contents-toggle').innerHTML =
+        showLabel);
+}
+
+documentReady(function () {
+  document
+    .querySelector('#technote-contents-toggle')
+    .addEventListener('click', toggleContentsOutline);
+
+  document.querySelectorAll('.technote-outline-container a').forEach((el) => {
+    el.addEventListener('click', toggleContentsOutline);
+  });
+  console.log(
+    '[Technote]: Added listener for contents outline navigation button.'
+  );
+});