Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[cherry-pick] Enhance UX on TorchAudio pages to improve awareness of doc versioning… #3267

Merged
merged 1 commit into from
Apr 24, 2023
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Enhance UX on TorchAudio pages to improve awareness of doc versioning (
…#3167)

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
  • Loading branch information
carljparker committed Apr 16, 2023
commit d8b35fa4415cdc90d6d4df6fca493f434ab46614
97 changes: 97 additions & 0 deletions docs/source/_templates/breadcrumbs.html
Original file line number Diff line number Diff line change
@@ -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>
2 changes: 1 addition & 1 deletion docs/source/_templates/layout.html
Original file line number Diff line number Diff line change
@@ -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 %}
9 changes: 9 additions & 0 deletions docs/source/conf.py
Original file line number Diff line number Diff line change
@@ -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