Merge pull request #38 from lsst-sqre/tickets/DM-41917

DM-41917: Add authors to the main column of text

CHANGELOG.md

@@ -2,6 +2,25 @@
 
 <!-- scriv-insert-here -->
 
+<a id='changelog-0.6.0'></a>
+## 0.6.0 (2023-12-05)
+
+### New features
+
+- Add `#svg-octicon-versions-16` to the `octicons.html` sprite template. This icon is useful for linking to alternative versions of a technote.
+
+- Add `#svg-octicon-mortar-board-16` to the `octicons.html` sprite template. This icon is useful for linking to the document's citation.
+
+- Export a variable, `T` from `technote.sphinxconf` that is an instance of `technote.main.TechnoteSphinxConfig`. This is useful for organizations that need to access the technote configuration and metadata in their own technote theme.
+
+- Figures and tables with captions are now numbered using the Sphinx `numfig` configuration. Authors can reference figures by number using the `numref` role pointing to the figure's `name` option.
+
+- Authors are now listed below the title of the technote. This is a change from the previous behavior of listing authors in the sidebar.
+
+### Bug fixes
+
+- Fix the `sidebar-authors.html` component template so that extra spaces aren't introduced between authors and commas.
+
 <a id='changelog-0.5.1'></a>
 ## 0.5.1 (2023-11-29)
 

demo/rst/index.rst

@@ -207,6 +207,7 @@ Figures
 
 .. figure:: https://placehold.co/600x400/000000/FFFFFF.png
    :alt: A placeholder image
+   :name: fig-placeholder
 
    This is an image.
 
@@ -220,6 +221,8 @@ This is a large image:
 .. image:: rubin-watermark.png
    :alt: A placeholder image
 
+Referencing a figure: :numref:`fig-placeholder`.
+
 Tables
 ======
 

docs/api.rst

@@ -19,7 +19,7 @@ Python API reference
 .. automodapi:: technote.ext.abstract
    :include-all-objects:
 
-.. automodapi:: technote.ext.insertstatus
+.. automodapi:: technote.ext.insertposttitle
    :include-all-objects:
 
 .. automodapi:: technote.ext.metadata

src/assets/styles/components/_index.scss

@@ -1,5 +1,6 @@
 @use 'article-header';
 @use 'icon-metadata';
+@use 'inline_authors';
 @use 'sidebar';
 @use 'sidebar-section';
 @use 'sidebar-logo';

src/assets/styles/components/_inline_authors.scss

@@ -0,0 +1,7 @@
+/*
+ * Styles for the author list that appears below the title.
+ */
+
+.technote-status + .technote-inline-authors {
+  margin-top: 2rem;
+}

src/assets/styles/utilities/_index.scss

@@ -35,3 +35,18 @@
 .technote-inline-comma-list li:nth-last-child(3) ~ li:nth-last-child(2):after {
   content: ', and ';
 }
+
+/*
+ * Hiding class, making content visible only to screen readers but not visually
+ * "sr" meaning "screen-reader"
+ * https://css-tricks.com/inclusively-hidden/
+ */
+.sr-only:not(:focus):not(:active) {
+  clip: rect(0 0 0 0);
+  clip-path: inset(50%);
+  height: 1px;
+  overflow: hidden;
+  position: absolute;
+  white-space: nowrap;
+  width: 1px;
+}

src/technote/ext/__init__.py

@@ -16,7 +16,7 @@
     visit_abstract_node_html,
     visit_abstract_node_tex,
 )
-from .insertstatus import insert_status
+from .insertposttitle import insert_post_title
 from .metadata import process_html_page_context_for_metadata
 from .pygmentscss import overwrite_pygments_css
 from .toc import process_html_page_context_for_toc
@@ -44,7 +44,7 @@ def setup(app: Sphinx) -> dict[str, Any]:
     app.connect("builder-inited", _add_js_file)
 
     app.connect("build-finished", wrap_html_tables)
-    app.connect("build-finished", insert_status)
+    app.connect("build-finished", insert_post_title)
     app.connect("build-finished", overwrite_pygments_css)
 
     return {

src/technote/ext/insertstatus.py → src/technote/ext/insertposttitle.py

@@ -9,17 +9,18 @@
 from jinja2 import Environment, PackageLoader, select_autoescape
 from sphinx.application import Sphinx
 
-from ..metadata.model import TechnoteState
 from ..templating.context import TechnoteJinjaContext
 
-__all__ = ["insert_status"]
+__all__ = ["insert_post_title"]
 
 
-def insert_status(app: Sphinx, exceptions: Exception | None) -> None:
-    """Insert a status aside into the technote, directly below the title.
+def insert_post_title(app: Sphinx, exceptions: Exception | None) -> None:
+    """Insert a html templates directly below the title.
 
-    The status aside is only added for non-stable states (draft, deprecated,
-    or other).
+    This extension adds the following HTML templates below the h1 section:
+
+    - The status aside is only added for non-stable states (draft, deprecated,
+      or other).
     """
     if exceptions:
         return
@@ -31,17 +32,13 @@ def insert_status(app: Sphinx, exceptions: Exception | None) -> None:
 
     technote_context = cast(TechnoteJinjaContext, technote_context)
 
-    status = technote_context.metadata.status
-    if status.state == TechnoteState.stable:
-        return
-
     # Load template from templates/status.html.jinja
     jinja_env = Environment(
         loader=PackageLoader("technote", "ext/templates"),
         autoescape=select_autoescape(["html"]),
     )
-    template = jinja_env.get_template("status.html.jinja")
-    status_html = template.render(status=status)
+    template = jinja_env.get_template("post-title.html.jinja")
+    status_html = template.render(technote=technote_context)
     status_soup = BeautifulSoup(status_html, "html.parser")
 
     # Insert the status aside into the technote

src/technote/ext/templates/post-title.html.jinja

@@ -0,0 +1,47 @@
+{% if technote.metadata.status.state != "stable" %}
+<aside class="technote-status technote-status--{{ technote.metadata.status.state.value }}">
+  <p class="technote-status__note" data-technote-status="{{ technote.metadata.status.state.value }}">
+  {% if technote.metadata.status.state == "draft" %}
+  This is a draft.
+  {% if technote.metadata.status.note %}
+  {{ technote.metadata.status.note }}
+  {% endif %}
+  </p>
+
+  {% elif technote.metadata.status.state == "deprecated" %}
+  This document is deprecated.
+  {% if technote.metadata.status.note %}
+  {{ technote.metadata.status.note }}
+  {% endif %}
+  </p>
+
+  {% if technote.metadata.status.supersceding_urls %}
+  <p>See instead:</p>
+
+  <ul>
+  {% for link in technote.metadata.status.supersceding_urls %}
+    <li><a href="{{ link.url }}" class="technote-superceding-url">{{ link.title or link.url }}</a></li>
+  {% endfor %}
+  </ul>
+  {% endif %}
+
+  {% elif technote.metadata.status.state == "other" %}
+  {{ status.note }}
+  </p>
+  {% endif %}
+</aside>
+{% endif %}
+
+{% if technote.metadata.authors %}
+<aside class="technote-inline-authors">
+
+<p class="sr-only">By:</p>
+
+<ul class="technote-inline-comma-list technote-sidebar-author-list">
+  {% for author in technote.metadata.authors %}
+  <li class="technote-sidebar-author-list__author p-author">{{ author.name.plain_text_name }}</li>
+  {% endfor %}
+</ul>
+
+</aside>
+{% endif %}

src/technote/sphinxconf.py

@@ -25,6 +25,7 @@
     "nitpicky",
     "nitpick_ignore",
     "nitpick_ignore_regex",
+    "numfig",
     # INTERSPHINX
     "intersphinx_mapping",
     "intersphinx_timeout",
@@ -91,6 +92,9 @@
 nitpick_ignore_regex: list[tuple[str, str]] = []
 T.append_nitpick_ignore_regex(nitpick_ignore_regex)
 
+# Number figures and tables with captions
+numfig = True
+
 # ============================================================================
 # INTERSPHINX Intersphinx settings
 # ============================================================================

src/technote/theme/sections/sidebar-primary.html

@@ -1,8 +1,6 @@
 <div class="technote-sidebar-container">
 {% include "components/sidebar-logo.html" %}
 
-{% include "components/sidebar-authors.html" %}
-
 {% include "components/sidebar-version.html" %}
 
 {% include "components/sidebar-source.html" %}

tests/metadata_test.py

@@ -80,7 +80,9 @@ def test_metadata_basic(app: Sphinx, status: IO, warning: IO) -> None:
         if "h-entry" in h_item["type"]:
             detected_hentry = True
             props = h_item["properties"]
-            assert props["author"][0] == "Jonathan Sick"
+            # The post-build cleanup doesn't run with the test builder,
+            # so the insertposttitle extension doesn't run; hence inline
+            # author info won't be added.
             assert props["updated"][0] == "2023-09-19T00:00:00Z"
             assert "content" in props
             assert "summary" in props