From 7ca7295c46da60b26b531de84dbe196d245a9ee2 Mon Sep 17 00:00:00 2001 From: Thomas Sibley Date: Thu, 27 Jan 2022 13:34:56 -0800 Subject: [PATCH 1/4] Use "subproject" theme option instead of overloading "logo_only" "logo_only" doesn't get at what this theme really wants to know, which is if the project is the main docs project or a subproject. This became blindly clear when I needed to know the same thing in a different template, which has nothing to do with logos. --- README.rst | 14 +++++++++++--- lib/nextstrain/sphinx/theme/layout.html | 6 +----- lib/nextstrain/sphinx/theme/theme.conf | 1 + 3 files changed, 13 insertions(+), 8 deletions(-) diff --git a/README.rst b/README.rst index 106b11b..3c74c7d 100644 --- a/README.rst +++ b/README.rst @@ -21,9 +21,9 @@ 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. @@ -31,6 +31,14 @@ options are supported: :logo_link: URL to use for the logo's link. Defaults to . +: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 . 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. diff --git a/lib/nextstrain/sphinx/theme/layout.html b/lib/nextstrain/sphinx/theme/layout.html index e497f82..a4cd222 100644 --- a/lib/nextstrain/sphinx/theme/layout.html +++ b/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 @@ {% endif %} -{% if not theme_logo_only %} +{% if theme_subproject %}
{{ project }} diff --git a/lib/nextstrain/sphinx/theme/theme.conf b/lib/nextstrain/sphinx/theme/theme.conf index bf57727..b165d30 100644 --- a/lib/nextstrain/sphinx/theme/theme.conf +++ b/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 From 7979ddfd9eb73de8e14d247b1144327ea1a4e1eb Mon Sep 17 00:00:00 2001 From: Thomas Sibley Date: Thu, 27 Jan 2022 11:48:33 -0800 Subject: [PATCH 2/4] =?UTF-8?q?Remove=20"Click=20here=20to=20return=20?= =?UTF-8?q?=E2=80=A6"=20message=20from=20subproject=20sidebars?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The logo now links to the doc home page, and we can improve wayfinding in other ways, like improving the page breadcrumbs. --- lib/nextstrain/sphinx/theme/layout.html | 4 ---- lib/nextstrain/sphinx/theme/static/css/nextstrain.css | 9 +-------- 2 files changed, 1 insertion(+), 12 deletions(-) diff --git a/lib/nextstrain/sphinx/theme/layout.html b/lib/nextstrain/sphinx/theme/layout.html index a4cd222..b8d0130 100644 --- a/lib/nextstrain/sphinx/theme/layout.html +++ b/lib/nextstrain/sphinx/theme/layout.html @@ -52,10 +52,6 @@
-
- (Click here to return to the main nextstrain docs) -
- {% endif %} {% include "searchbox.html" %} diff --git a/lib/nextstrain/sphinx/theme/static/css/nextstrain.css b/lib/nextstrain/sphinx/theme/static/css/nextstrain.css index ba0bc28..86d21a2 100644 --- a/lib/nextstrain/sphinx/theme/static/css/nextstrain.css +++ b/lib/nextstrain/sphinx/theme/static/css/nextstrain.css @@ -78,6 +78,7 @@ 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; @@ -90,14 +91,6 @@ footer span.commit code, 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"] { From f20aa26e638d2a6b225145e66a2d0e766eda810e Mon Sep 17 00:00:00 2001 From: Thomas Sibley Date: Thu, 27 Jan 2022 13:38:11 -0800 Subject: [PATCH 3/4] Improve breadcrumbs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Starts breadcrumbs with the main Nextstrain doc home page to replace the previous "click here" link and situate the subproject within the larger docs. - Replaces home icon with the word "Home" for less mystery-meat nav. - Replaces » with / for separating breadcrumb levels as a more traditional hierarchy marker. - Removes current page title from breadcrumbs to avoid repeating ourselves. --- lib/nextstrain/sphinx/theme/breadcrumbs.html | 41 +++++++++++++++++++ .../sphinx/theme/static/css/nextstrain.css | 15 +++++++ 2 files changed, 56 insertions(+) create mode 100644 lib/nextstrain/sphinx/theme/breadcrumbs.html diff --git a/lib/nextstrain/sphinx/theme/breadcrumbs.html b/lib/nextstrain/sphinx/theme/breadcrumbs.html new file mode 100644 index 0000000..5d162c9 --- /dev/null +++ b/lib/nextstrain/sphinx/theme/breadcrumbs.html @@ -0,0 +1,41 @@ +{% extends "sphinx_rtd_theme/breadcrumbs.html" %} + +{% block breadcrumbs %} + {# Separators between
  • 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 %} +
  • Home
    • +
  • {{ project }}
    • + {% else %} +
  • Home
    • + {% endif %} + + {# + The parents of the current page, according to the project toctree, without + the root doc (master_doc). + #} + {% for doc in parents %} +
  • {{ doc.title }}
    • + {% 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 %} diff --git a/lib/nextstrain/sphinx/theme/static/css/nextstrain.css b/lib/nextstrain/sphinx/theme/static/css/nextstrain.css index 86d21a2..9511c40 100644 --- a/lib/nextstrain/sphinx/theme/static/css/nextstrain.css +++ b/lib/nextstrain/sphinx/theme/static/css/nextstrain.css @@ -180,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
  • s + * in the template and the 5px _left_ padding on
  • s. The result is that + * the slash (/) is centered between the end of the previous
  • 's text and + * start of this
  • '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 */ From a1725879aabc434d5b42e8fca01a2d561fd43a99 Mon Sep 17 00:00:00 2001 From: Thomas Sibley Date: Thu, 27 Jan 2022 11:50:11 -0800 Subject: [PATCH 4/4] Improve version verbiage MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The most common case is now cleaner: version: stable → nothing The meaning of "latest" is now clearer: version: latest → development version and a useless colon is dropped: version: X → version X Versions are always always on their own (centered) line now underneath the subproject name, instead of potentially sitting alongside them for short names (like "CLI"). --- lib/nextstrain/sphinx/theme/layout.html | 12 +++++++++--- .../sphinx/theme/static/css/nextstrain.css | 4 ++-- 2 files changed, 11 insertions(+), 5 deletions(-) diff --git a/lib/nextstrain/sphinx/theme/layout.html b/lib/nextstrain/sphinx/theme/layout.html index b8d0130..ad7bf77 100644 --- a/lib/nextstrain/sphinx/theme/layout.html +++ b/lib/nextstrain/sphinx/theme/layout.html @@ -45,9 +45,15 @@ {%- set nav_version = current_version %} {% endif %} {% if nav_version %} - - version: {{ nav_version }} - +
    + {% if nav_version == "stable" %} + {# don't show anything #} + {% elif nav_version == "latest" %} + development version + {% else %} + version {{ nav_version }} + {% endif %} +
    {% endif %} diff --git a/lib/nextstrain/sphinx/theme/static/css/nextstrain.css b/lib/nextstrain/sphinx/theme/static/css/nextstrain.css index 9511c40..3ebe173 100644 --- a/lib/nextstrain/sphinx/theme/static/css/nextstrain.css +++ b/lib/nextstrain/sphinx/theme/static/css/nextstrain.css @@ -85,8 +85,8 @@ footer span.commit code, 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);