Enhance UX on TorchAudio pages to improve awareness of doc versioning (…

…#3167) (#3267)

Summary:
- Boldface the version-selection UX and increase size by three percent.
- Add text to breadcrumbs to indicate version and stability.
- New `breadcrumbs.html` in `_templates` overrides Sphinx version.

I create a new variable in `conf.py`, **version_stable**, which has the version number for the most-recent stable release. I define this variable in the **html_context** dictionary so that it is visible to the templates.

I use this approach because I was not able to find any other way of discerning the current stable release during the build. Note that the `versions.html` file--which identifies the current stable release--appears to be available only in the **gh-pages** branch and so it is not available at build time.

However, this means that someone will need to update `conf.py` whenever the current stable release changes.

Pull Request resolved: #3167

Reviewed By: mthrok

Differential Revision: D44112224

Pulled By: carljparker

fbshipit-source-id: e76f5cb6734a784d161342964459577aa9b64cac

docs/source/_templates/breadcrumbs.html

@@ -0,0 +1,97 @@
+{# Support for Sphinx 1.3+ page_source_suffix, but don't break old builds. #}
+
+{% if page_source_suffix %}
+{% set suffix = page_source_suffix %}
+{% else %}
+{% set suffix = source_suffix %}
+{% endif %}
+
+{% if meta is defined and meta is not none %}
+{% set check_meta = True %}
+{% else %}
+{% set check_meta = False %}
+{% endif %}
+
+{% if check_meta and 'github_url' in meta %}
+{% set display_github = True %}
+{% endif %}
+
+{% if check_meta and 'bitbucket_url' in meta %}
+{% set display_bitbucket = True %}
+{% endif %}
+
+{% if check_meta and 'gitlab_url' in meta %}
+{% set display_gitlab = True %}
+{% endif %}
+
+<div role="navigation" aria-label="breadcrumbs navigation">
+
+  <ul class="pytorch-breadcrumbs">
+    {% block breadcrumbs %}
+      <li>
+        <a href="{{ pathto(master_doc) }}">
+          {% if theme_pytorch_project == 'tutorials' %}
+            Tutorials
+          {% else %}
+            Docs
+          {% endif %}
+        </a> &gt;
+      </li>
+
+        {% for doc in parents %}
+          <li><a href="{{ doc.link|e }}">{{ doc.title }}</a> &gt;</li>
+        {% endfor %}
+      <li>{{ title }} &gt;</li>
+      {% if 'Nightly' in version %}
+      <li>Nightly (unstable)</li>
+      {% elif version_stable in version %}
+      <li>Current (stable)</li>
+      {% else %}
+      <li>Old version (stable)</li>
+      {% endif %}
+    {% endblock %}
+    {% block breadcrumbs_aside %}
+      <li class="pytorch-breadcrumbs-aside">
+        {% if hasdoc(pagename) %}
+            {% if display_github %}
+            {% if check_meta and 'github_url' in meta %}
+              <!-- User defined GitHub URL -->
+              <a href="{{ meta['github_url'] }}" class="fa fa-github"> {{ _('Edit on GitHub') }}</a>
+            {% else %}
+              <a href="https://{{ github_host|default("github.com") }}/{{ github_user }}/{{ github_repo }}/{{ theme_vcs_pageview_mode|default("blob") }}/{{ github_version }}{{ conf_py_path }}{{ pagename }}{{ suffix }}" class="fa fa-github"> {{ _('Edit on GitHub') }}</a>
+            {% endif %}
+          {% elif display_bitbucket %}
+            {% if check_meta and 'bitbucket_url' in meta %}
+              <!-- User defined Bitbucket URL -->
+              <a href="{{ meta['bitbucket_url'] }}" class="fa fa-bitbucket"> {{ _('Edit on Bitbucket') }}</a>
+            {% else %}
+              <a href="https://bitbucket.org/{{ bitbucket_user }}/{{ bitbucket_repo }}/src/{{ bitbucket_version}}{{ conf_py_path }}{{ pagename }}{{ suffix }}?mode={{ theme_vcs_pageview_mode|default("view") }}" class="fa fa-bitbucket"> {{ _('Edit on Bitbucket') }}</a>
+            {% endif %}
+          {% elif display_gitlab %}
+            {% if check_meta and 'gitlab_url' in meta %}
+              <!-- User defined GitLab URL -->
+              <a href="{{ meta['gitlab_url'] }}" class="fa fa-gitlab"> {{ _('Edit on GitLab') }}</a>
+            {% else %}
+              <a href="https://{{ gitlab_host|default("gitlab.com") }}/{{ gitlab_user }}/{{ gitlab_repo }}/{{ theme_vcs_pageview_mode|default("blob") }}/{{ gitlab_version }}{{ conf_py_path }}{{ pagename }}{{ suffix }}" class="fa fa-gitlab"> {{ _('Edit on GitLab') }}</a>
+            {% endif %}
+          {% elif show_source and source_url_prefix %}
+            <a href="{{ source_url_prefix }}{{ pagename }}{{ suffix }}"><img src="{{ pathto('_static/images/view-page-source-icon.svg', 1) }}"></a>
+          {% elif show_source and has_source and sourcename %}
+            <a href="{{ pathto('_sources/' + sourcename, true)|e }}" rel="nofollow"><img src="{{ pathto('_static/images/view-page-source-icon.svg', 1) }}"></a>
+          {% endif %}
+        {% endif %}
+      </li>
+    {% endblock %}
+  </ul>
+
+  {% if (theme_prev_next_buttons_location == 'top' or theme_prev_next_buttons_location == 'both') and (next or prev) %}
+  <div class="rst-breadcrumbs-buttons" role="navigation" aria-label="breadcrumb navigation">
+      {% if next %}
+        <a href="{{ next.link|e }}" class="btn btn-neutral float-right" title="{{ next.title|striptags|e }}" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
+      {% endif %}
+      {% if prev %}
+        <a href="{{ prev.link|e }}" class="btn btn-neutral" title="{{ prev.title|striptags|e }}" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
+      {% endif %}
+  </div>
+  {% endif %}
+</div>

docs/source/_templates/layout.html

@@ -2,7 +2,7 @@
 
 {% block sidebartitle %}
     <div class="version">
-      <a href="{{ pathto('../versions.html', 1) }}">{{ version }} &#x25BC</a>
+      <a href="{{ pathto('../versions.html', 1) }}"><span style="font-size:110%">{{ version }} &#x25BC</span></a>
     </div>
     {% include "searchbox.html" %}
 {% endblock %}

docs/source/conf.py

@@ -176,6 +176,15 @@ def _get_pattern():
     version = f"Nightly Build ({torchaudio.__version__})"
     release = "nightly"
 
+
+#
+# Specify the version of the current stable release.
+# Used in `docs/source/_templates/breadcrumbs.html`
+#
+# https://stackoverflow.com/a/33845358/1106930
+#
+html_context = {"version_stable": "2.0.1"}
+
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path