Improve breadcrumbs and version verbiage

README.rst

@@ -21,16 +21,24 @@ your ``conf.py`` file:
 
     html_theme = "nextstrain-sphinx-theme"
 
-This theme is based on sphinx_rtd_theme_ and accepts all of the same
-`configuration options`_ settable via ``html_theme_option``.  Two additional
-options are supported:
+This theme is based on sphinx_rtd_theme_ and accepts most of the same
+`configuration options`_ settable via ``html_theme_option`` and a few
+additional options as well:
 
 :logo: Boolean determining if the Nextstrain logo should be displayed.
        Defaults to true.
 
 :logo_link: URL to use for the logo's link.  Defaults to
             <https://docs.nextstrain.org>.
 
+:logo_only: Ignored.  Inherited from sphinx_rtd_theme_.  Instead, the project
+            name and version info will not be displayed (thus showing only the
+            logo) when ``subproject`` is true.
+
+:subproject: Boolean determining if this is a subproject of the main Nextstrain
+             documentation project on <https://docs.nextstrain.org>.  Defaults
+             to true.
+
 If your project wants to display its own logo, just set Sphinx's ``html_logo``
 to point to the image file in your Sphinx project.
 

lib/nextstrain/sphinx/theme/breadcrumbs.html

@@ -0,0 +1,41 @@
+{% extends "sphinx_rtd_theme/breadcrumbs.html" %}
+
+{% block breadcrumbs %}
+  {# Separators between <li>s are added by CSS. #}
+
+  {#
+    Breadcrumbs always start with home icon pointing to the main Nextstrain doc
+    project.
+
+    If the current project is the main project, then we don't hardcode the URL
+    so the currently viewed version/language is preserved (although we don't
+    use these features currently).
+  #}
+  {% if theme_subproject %}
+    <li><a href="https://docs.nextstrain.org">Home</a></li>
+    <li><a href="{{ pathto(master_doc) }}">{{ project }}</a></li>
+  {% else %}
+    <li><a href="{{ pathto(master_doc) }}">Home</a></li>
+  {% endif %}
+
+  {#
+    The parents of the current page, according to the project toctree, without
+    the root doc (master_doc).
+  #}
+  {% for doc in parents %}
+    <li><a href="{{ doc.link|e }}">{{ doc.title }}</a></li>
+  {% endfor %}
+
+  {#
+    Don't include the current page's title (like the template we're extending
+    does) because the page title is immediately below these breadcrumbs anyway.
+
+    This also follows common UX recommendations for breadcrumbs, e.g. the UK's
+    Government Digital Service (gov.uk) breadcrumbs component guidelines¹ says:
+
+        The breadcrumb should start with your ‘home’ page and end with the
+        parent section of the current page.
+
+    ¹ https://design-system.service.gov.uk/components/breadcrumbs/
+  #}
+{% endblock %}

lib/nextstrain/sphinx/theme/layout.html

@@ -18,10 +18,6 @@
   by the theme *and also* can't refer to a theme-provided file when set by the
   doc project's conf.py.
 
-  `theme_logo_only` is set via a project's conf.py -> `html_theme_options` ->
-  `logo_only` value (default: false). In the context of Nextstrain we use this
-  to determine whether or not to display the subproject name, version
-
   We also adjust the rendering of the project name to remove the home icon.
 #}
 {% block sidebartitle %}
@@ -34,7 +30,7 @@
   </a>
 {% endif %}
 
-{% if not theme_logo_only %}
+{% if theme_subproject %}
   <div class="subproject">
     <a href="{{ pathto(master_doc) }}" class="project-name" alt="{{ _("Documentation Home") }}">
       {{ project }}
@@ -49,17 +45,19 @@
       {%- set nav_version = current_version %}
     {% endif %}
     {% if nav_version %}
-      <span>
-        version: {{ nav_version }}
-      </span>
+      <div class="version">
+        {% if nav_version == "stable" %}
+          {# don't show anything #}
+        {% elif nav_version == "latest" %}
+          development version
+        {% else %}
+          version {{ nav_version }}
+        {% endif %}
+      </div>
     {% endif %}
 
   </div>
 
-  <div>
-    (<a href="https://docs.nextstrain.org">Click here</a> to return to the main nextstrain docs)
-  </div>
-
 {% endif %}
 
 {% include "searchbox.html" %}

lib/nextstrain/sphinx/theme/static/css/nextstrain.css

@@ -78,26 +78,19 @@ footer span.commit code,
 /* Sub-project name, version (optional) and link back to the main docs */
 .wy-side-nav-search > div.subproject {
   margin-top: -1rem;
+  margin-bottom: 1.2rem;
 }
 .wy-side-nav-search > div.subproject > a { /* subproject name */
   font-size: 1.5rem;
   font-weight: 500;
   color: var(--heading-color);
 }
-.wy-side-nav-search > div.subproject > span { /* version name */
-  display: inline-block;
+.wy-side-nav-search > div.subproject > .version { /* version name */
+  display: block;
   font-size: 1.1rem;
   font-weight: 300;
   color: var(--heading-color);
 }
-.wy-side-nav-search > div.subproject + div { /* go back to main docs link */
-  font-style: italic;
-  font-size: 1rem;
-  font-weight: 300;
-  line-height: 1rem;
-  color: var(--heading-color);
-  margin-bottom: 1.2rem;
-}
 
 /* Remove blue accent border */
 .wy-side-nav-search input[type="text"] {
@@ -187,6 +180,21 @@ footer span.commit code,
 }
 
 
+/* Breadcrumb separators (at top of the page) */
+.wy-breadcrumbs > li:not(:first-child):not(.wy-breadcrumbs-aside)::before {
+  display: inline-block;
+  content: "/\A0"; /* \A0 = no-break space (nbsp) */
+  padding-right: 5px;
+
+  /* The trailing space + 5px _right_ padding matches the amount of whitespace
+   * on the other side of the slash (/) the comes from the spaces between <li>s
+   * in the template and the 5px _left_ padding on <li>s.  The result is that
+   * the slash (/) is centered between the end of the previous <li>'s text and
+   * start of this <li>'s text.
+   */
+}
+
+
 /* Footer styles. Largely chosen to mimic the previous rendering of the docs. See
 https://github.com/nextstrain/nextstrain.org/blob/b1e09e57e91ed0c9343e1cd3104877ec3c5344a4/static-site/src/components/Footer/index.jsx
 */

lib/nextstrain/sphinx/theme/theme.conf

@@ -8,3 +8,4 @@ pygments_style = default
 style_nav_header_background = #f2f2f2
 logo = True
 logo_link = https://docs.nextstrain.org
+subproject = True