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

DM-41917: Improvements to the technote UI design
lsst-sqre · Dec 5, 2023 · 995d627 · 995d627
2 parents cc03868 + 636cad2
commit 995d627
Show file tree

Hide file tree

Showing 22 changed files with 264 additions and 14 deletions.
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -1,3 +1,3 @@
-graft src/documenteer/assets/styles
+graft src/documenteer/assets
 graft src/documenteer/assets/scripts
 graft src/documenteer/assets/rsd-assets
diff --git a/changelog.d/20231201_154001_jsick_DM_41917.md b/changelog.d/20231201_154001_jsick_DM_41917.md
@@ -0,0 +1,5 @@
+### New features
+
+- Use the Source Sans 3 variable font in technotes.
+- Small improvements to the technote UI, including: linking to the *LSST the Docs* editions dashboards, showing the Rubin imagotype on mobile views, and moving the author listing to the main text column. In mobile, headers are also smaller and more compact to conserve vertical space.
+- Upgrade to technote 0.6.
diff --git a/demo/rst-technote/index.rst b/demo/rst-technote/index.rst
@@ -60,6 +60,8 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin facilisis pharetr
 
    git add index.rst
 
+Some following text.
+
 .. mermaid::
 
    graph TD

diff --git a/demo/rst-technote/technote.toml b/demo/rst-technote/technote.toml
@@ -15,3 +15,11 @@ orcid = "https://orcid.org/0000-0003-3001-676X"
 affiliations = [
     { name = "Rubin Observatory", ror = "https://ror.org/048g3cy84" }
 ]
+
+[[technote.authors]]
+name.given = "Frossie"
+name.family = "Economou"
+
+[[technote.authors]]
+name.given = "Russ"
+name.family = "Allbery"
diff --git a/pyproject.toml b/pyproject.toml
@@ -96,7 +96,7 @@ pipelines = [
 ]
 technote = [
     # Theme and extensions for technotes
-    "technote>=0.5.0,<0.6.0",
+    "technote>=0.6.0,<0.7.0",
     "sphinx-prompt",
     "sphinxcontrib-mermaid",
     "sphinx-diagrams",

diff --git a/src/assets/rubin-technote/styles/SourceSans3VF-Italic.ttf.woff2 b/src/assets/rubin-technote/styles/SourceSans3VF-Italic.ttf.woff2
diff --git a/src/assets/rubin-technote/styles/SourceSans3VF-Upright.ttf.woff2 b/src/assets/rubin-technote/styles/SourceSans3VF-Upright.ttf.woff2
diff --git a/src/assets/rubin-technote/styles/_hacks.scss b/src/assets/rubin-technote/styles/_hacks.scss
@@ -3,3 +3,27 @@
  * other selectors. These selectors should eventually be refactored into
  * 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.
+ */
+.highlight-default .highlight {
+  border: var(--tn-sphinx-code-block-border-thickness) solid
+    var(--tn-sphinx-code-block-border-color);
+  border-radius: var(--tn-sphinx-code-block-border-radius);
+}
+.highlight-default .highlight pre {
+  margin: 1em;
+}
diff --git a/src/assets/rubin-technote/styles/_properties.scss b/src/assets/rubin-technote/styles/_properties.scss
@@ -2,9 +2,50 @@
  * Override technote CSS properties with Rubin Style Dictionary.
  */
 
+@font-face {
+  font-family: 'Source Sans 3 VF';
+  font-weight: 200 900;
+  font-style: normal;
+  font-stretch: normal;
+  src: url('./SourceSans3VF-Upright.ttf.woff2') format('woff2');
+}
+
+@font-face {
+  font-family: 'Source Sans 3 VF';
+  font-weight: 200 900;
+  font-style: italic;
+  font-stretch: normal;
+  src: url('./SourceSans3VF-Italic.ttf.woff2') format('woff2');
+}
+
 :root {
+  --tn-component-text-font-family: 'Source Sans 3 VF', -apple-system,
+    BlinkMacSystemFont, Segoe UI, Roboto, Oxygen, Ubuntu, Cantarell, Fira Sans,
+    Droid Sans, Helvetica Neue, sans-serif;
   --tn-component-text-color: var(--rsd-component-text-color);
   --tn-component-toc-header-color: var(--rsd-color-primary-600);
   --tn-component-sidebar-header-color: var(--rsd-color-primary-600);
   --tn-component-toc-level-border-color: var(--rsd-color-primary-600);
 }
+
+@supports (font-variation-settings: 'wdth' 222) {
+  :root {
+    --tn-component-h1-weight: 600;
+    --tn-component-h2-weight: 500;
+    --tn-component-h3-weight: 600;
+    --tn-component-h4-weight: 700;
+    --tn-component-h5-weight: 800;
+    --tn-component-h6-weight: 800;
+  }
+}
+
+@media (max-width: 76rem) {
+  :root {
+    --tn-component-h1-size: 2.4rem;
+    --tn-component-h2-size: 1.8rem;
+    --tn-component-h3-size: 1.2rem;
+    --tn-component-h4-size: 1rem;
+    --tn-component-h5-size: 1rem;
+    --tn-component-h6-size: 1rem;
+  }
+}
diff --git a/src/assets/rubin-technote/styles/components/_article-header.scss b/src/assets/rubin-technote/styles/components/_article-header.scss
@@ -0,0 +1,22 @@
+.mobile-rubin-technote-logo {
+  display: block;
+  margin: 0 auto 2rem auto;
+  width: 100%;
+  max-width: 12rem;
+}
+
+@media (max-width: 76rem) {
+  // When the primary sidebar is hidden, remove extra top margin from the
+  // container so the logo is closer to the top.
+  .sb-container {
+    margin-top: 0;
+  }
+}
+
+@media (min-width: 76rem) {
+  // Hide the mobile logo when the primary sidebar is visible.
+  .mobile-rubin-technote-logo {
+    display: none;
+    margin: 0;
+  }
+}
diff --git a/src/assets/rubin-technote/styles/components/_authors.scss b/src/assets/rubin-technote/styles/components/_authors.scss
@@ -0,0 +1,8 @@
+/*
+ * Custom styles for the author listing.
+ */
+
+.technote-inline-authors {
+  font-size: 1.1rem;
+  font-weight: 425;
+}
diff --git a/src/assets/rubin-technote/styles/components/_index.scss b/src/assets/rubin-technote/styles/components/_index.scss
@@ -1,2 +1,5 @@
+@use 'authors.scss';
 @use 'global-breadcrumbs.scss';
 @use 'version-info.scss';
+@use 'sidebar-section.scss';
+@use 'article-header.scss';
diff --git a/src/assets/rubin-technote/styles/components/_sidebar-section.scss b/src/assets/rubin-technote/styles/components/_sidebar-section.scss
@@ -0,0 +1,7 @@
+@supports (font-variation-settings: 'wdth' 222) {
+  .technote-sidebar-section__heading {
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.01em; // goes well with upper case
+  }
+}
diff --git a/src/assets/rubin-technote/styles/components/_version-info.scss b/src/assets/rubin-technote/styles/components/_version-info.scss
@@ -19,3 +19,9 @@
 .rubin-technote-version-info > p:last-child {
   margin-right: 0;
 }
+
+@supports (font-variation-settings: 'wdth' 222) {
+  .rubin-technote-version-info a {
+    font-weight: 500;
+  }
+}
diff --git a/src/documenteer/assets/.gitignore b/src/documenteer/assets/.gitignore
@@ -1,4 +1,6 @@
 # Generated by webpack
 rsd-assets/
 scripts/
-styles/
+*.woff2
+rubin-technote.css
+rubin-technote.css.map
diff --git a/src/documenteer/conf/__init__.py b/src/documenteer/conf/__init__.py
@@ -1,4 +1,13 @@
 from ._toml import DocumenteerConfig
-from ._utils import get_asset_path, get_template_dir
+from ._utils import (
+    extend_static_paths_with_asset_extension,
+    get_asset_path,
+    get_template_dir,
+)
 
-__all__ = ["get_asset_path", "get_template_dir", "DocumenteerConfig"]
+__all__ = [
+    "get_asset_path",
+    "extend_static_paths_with_asset_extension",
+    "get_template_dir",
+    "DocumenteerConfig",
+]
diff --git a/src/documenteer/conf/_utils.py b/src/documenteer/conf/_utils.py
@@ -7,7 +7,17 @@
 from git import Repo
 from sphinx.errors import ConfigError
 
-__all__ = ["get_asset_path", "get_template_dir", "GitRepository"]
+__all__ = [
+    "get_asset_path",
+    "extend_static_paths_with_asset_extension",
+    "get_template_dir",
+    "GitRepository",
+]
+
+
+def _get_assert_dir() -> Path:
+    """Get the absolute path to the Documenteer assets directory."""
+    return Path(__file__).parent.joinpath("../assets")
 
 
 def get_asset_path(name: str) -> str:
@@ -34,8 +44,7 @@ def get_asset_path(name: str) -> str:
            get_asset_path("rubin-titlebar-imagotype-light.svg"),
        ]
     """
-    asset_path = Path(__file__).parent.joinpath("../assets", name)
-    asset_path.resolve()
+    asset_path = _get_assert_dir().joinpath(name).resolve()
     if not asset_path.exists():
         raise ConfigError(
             f"Documenteer asset {name!r} does not exist.\n"
@@ -45,6 +54,17 @@ def get_asset_path(name: str) -> str:
     return str(asset_path)
 
 
+def extend_static_paths_with_asset_extension(
+    html_static_path: list[str], extension: str
+) -> None:
+    """Extend a Sphinx ``html_static_path`` configuration list with the
+    files of a given extension in Documenteer's assets directory.
+    """
+    asset_dir = _get_assert_dir()
+    for p in asset_dir.glob(f"*.{extension}"):
+        html_static_path.append(str(p))
+
+
 def get_template_dir(root: str) -> str:
     """Get the absolute path for a Documenteer template directory, for use
     with Sphinx's ``templates_path``.

diff --git a/src/documenteer/conf/technote.py b/src/documenteer/conf/technote.py
@@ -4,7 +4,11 @@
 
 from technote.sphinxconf import *  # noqa: F401 F403
 
-from documenteer.conf import get_asset_path, get_template_dir
+from documenteer.conf import (
+    extend_static_paths_with_asset_extension,
+    get_asset_path,
+    get_template_dir,
+)
 
 try:
     # Remove the sphinxcontrib-bibtex extension so that we can add it back
@@ -33,11 +37,12 @@
 html_static_path: list[str] = [
     get_asset_path("rubin-favicon-transparent-32px.png"),
     get_asset_path("rubin-favicon.svg"),
-    get_asset_path("styles/rubin-technote.css"),
-    get_asset_path("styles/rubin-technote.css.map"),
+    get_asset_path("rubin-technote.css"),
+    get_asset_path("rubin-technote.css.map"),
     get_asset_path("rsd-assets/rubin-imagotype-color-on-white-crop.svg"),
     get_asset_path("rsd-assets/rubin-imagotype-color-on-black-crop.svg"),
 ]
+extend_static_paths_with_asset_extension(html_static_path, "woff2")
 
 html_css_files = ["rubin-technote.css"]
 
@@ -78,3 +83,9 @@
 
 bibtex_default_style = "lsst_aa"
 bibtex_reference_style = "author_year"
+
+_id = T.metadata.id  # noqa: F405
+if _id is not None:
+    html_context[  # noqa: F405
+        "editions_url"
+    ] = f"https://{_id.lower()}.lsst.io/v/"
diff --git a/src/documenteer/templates/technote/components/sidebar-source.html b/src/documenteer/templates/technote/components/sidebar-source.html
@@ -0,0 +1,75 @@
+<section class="technote-sidebar-section">
+  <h2 class="technote-sidebar-section__heading">Source</h2>
+
+  <ul class="technote-sidebar-metadata-list technote-icon-pair-list">
+    {% if technote.github_url %}
+    <li>
+      <div class="technote-icon-metadata">
+        <div class="technote-icon-metadata__icon">
+          <a href="{{technote.github_url}}">
+            <svg class="technote-svg-icon">
+              <use href="#svg-octicon-octocat-16">
+            </svg>
+          </a>
+        </div>
+        <p class="technote-icon-metadata__value">
+          <a href="{{technote.github_url}}" data-technote-source-url="{{ technote.github_url }}">
+          {{ technote.github_repo_slug }}
+          </a>
+        </p>
+      </div>
+    </li>
+    {% endif %}
+    {% if technote.github_ref_name %}
+    <li>
+      <div class="technote-icon-metadata">
+        <div class="technote-icon-metadata__icon">
+          <svg class="technote-svg-icon">
+            {% if technote.github_ref_type == "tag" %}
+            <use href="#svg-octicon-tag-16">
+            {% else %}
+            <use href="#svg-octicon-branch-16">
+            {% endif %}
+          </svg>
+        </div>
+        <p class="technote-icon-metadata__value">
+          {{ technote.github_ref_name }}
+        </p>
+      </div>
+    </li>
+    {% endif %}
+    {% if technote.github_edit_url %}
+    <li>
+      <div class="technote-icon-metadata">
+        <div class="technote-icon-metadata__icon">
+          <a href="{{ technote.github_edit_url }}">
+            <svg class="technote-svg-icon">
+              <use href="#svg-octicon-pencil-16">
+            </svg>
+          </a>
+        </div>
+        <p class="technote-icon-metadata__value"><a href="{{ technote.github_edit_url }}">Edit on GitHub</a></p>
+      </div>
+    </li>
+    {% endif %}
+
+    {% if editions_url %}
+    <li>
+      <div class="technote-icon-metadata">
+        <div class="technote-icon-metadata__icon">
+          <a href="{{editions_url}}">
+            <svg class="technote-svg-icon">
+              <use href="#svg-octicon-versions-16">
+            </svg>
+          </a>
+        </div>
+        <p class="technote-icon-metadata__value">
+          <a href="{{editions_url}}">View all versions</a>
+        </p>
+      </div>
+    </li>
+    {% endif %}
+    <!-- <li>Commit?</li> -->
+    <!-- <li>CI run link?</li> -->
+  </ul>
+</section>
diff --git a/src/documenteer/templates/technote/sections/header-article.html b/src/documenteer/templates/technote/sections/header-article.html
@@ -1,4 +1,9 @@
 <div class="match-content-width">
+  <a class="mobile-rubin-technote-logo" href="{{ theme_logo_link_url or '#' }}">
+  <img class="technote-themed-light" src="{{ pathto('_static/' + theme_light_logo, 1) }}" alt="{{theme_logo_alt_text}}">
+  <img class="technote-themed-dark" src="{{ pathto('_static/' + theme_dark_logo, 1) }}" alt="{{theme_logo_alt_text}}">
+  </a>
+
   <ol class="rubin-technote-global-breadcrumbs">
     <li><a href="https://www.lsst.io/">Rubin Documentation</a></li>
     <li>
@@ -14,18 +19,22 @@
     {% if technote.version %}
     <p>
       <span class="rubin-technote-version-info__label">Version</span>
+      {% if editions_url %}<a href="{{editions_url}}">{% endif %}
       <span class="rubin-technote-version-info__value"
         >{{technote.version}}</span
       >
+      {% if editions_url %}</a>{% endif %}
     </p>
     {% endif %} {% if technote.date_updated_iso %}
     <p>
       <span class="rubin-technote-version-info__label">Updated</span>
+      {% if editions_url %}<a href="{{editions_url}}">{% endif %}
       <time
         class="rubin-technote-version-info__value"
         datetime="technote.date_updated_iso"
         >{{ technote.date_updated_iso }}</time
       >
+      {% if editions_url %} </a>{% endif %}
     </p>
     {% endif %}
   </div>