Search code examples
python-sphinxread-the-docs

Enable versions in sidebar in sphinx read the docs theme

I would like to include the versions.html in the sidebar and could not succeed.

I tried to add versions.html in ** for sidebars, this had no effect:

html_sidebars = {
    '**': ['versions.html']
}

Also how to declare the different versions in conf.py.

I have looked at sphinxcontrib-versioning but it is not exactly what I am looking for.

Solution

  • This can be achieved by adding a _templates/versions.html file to override the rtd theme's default jinja template file and adding some variables to the conf.py file.

    Execute the following to create a new '_templates/' directory and 'versions.html' file:

    mkdir _templates
cat > _templates/versions.html <<'EOF'
{% if READTHEDOCS or display_lower_left %}
{# Add rst-badge after rst-versions for small badge style. #}
  <div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
    <span class="rst-current-version" data-toggle="rst-current-version">
      <span class="fa fa-book"> Read the Docs</span>
      v: {{ current_version }}
      <span class="fa fa-caret-down"></span>
    </span>
    <div class="rst-other-versions">
      {% if languages|length >= 1 %}
      <dl>
        <dt>{{ _('Languages') }}</dt>
        {% for slug, url in languages %}
          {% if slug == current_language %} <strong> {% endif %}
          <dd><a href="{{ url }}">{{ slug }}</a></dd>
          {% if slug == current_language %} </strong> {% endif %}
        {% endfor %}
      </dl>
      {% endif %}
      {% if versions|length >= 1 %}
      <dl>
        <dt>{{ _('Versions') }}</dt>
        {% for slug, url in versions %}
          {% if slug == current_version %} <strong> {% endif %}
          <dd><a href="{{ url }}">{{ slug }}</a></dd>
          {% if slug == current_version %} </strong> {% endif %}
        {% endfor %}
      </dl>
      {% endif %}
      {% if downloads|length >= 1 %}
      <dl>
        <dt>{{ _('Downloads') }}</dt>
        {% for type, url in downloads %}
          <dd><a href="{{ url }}">{{ type }}</a></dd>
        {% endfor %}
      </dl>
      {% endif %}
      {% if READTHEDOCS %}
      <dl>
        <dt>{{ _('On Read the Docs') }}</dt>
          <dd>
            <a href="//{{ PRODUCTION_DOMAIN }}/projects/{{ slug }}/?fromdocs={{ slug }}">{{ _('Project Home') }}</a>
          </dd>
          <dd>
            <a href="//{{ PRODUCTION_DOMAIN }}/builds/{{ slug }}/?fromdocs={{ slug }}">{{ _('Builds') }}</a>
          </dd>
      </dl>
      {% endif %}
      <hr/>
      {% trans %}Free document hosting provided by <a href="http://www.readthedocs.org">Read the Docs</a>.{% endtrans %}
 
    </div>
  </div>
{% endif %}
 
EOF

    And execute the following to append to the conf.py file:

    cat >> conf.py <<'EOF'
 
############################
# SETUP THE RTD LOWER-LEFT #
############################
try:
   html_context
except NameError:
   html_context = dict()
html_context['display_lower_left'] = True

templates_path = ['_templates']

if 'REPO_NAME' in os.environ:
   REPO_NAME = os.environ['REPO_NAME']
else:
   REPO_NAME = ''
 
# SET CURRENT_LANGUAGE
if 'current_language' in os.environ:
   # get the current_language env var set by buildDocs.sh
   current_language = os.environ['current_language']
else:
   # the user is probably doing `make html`
   # set this build's current language to english
   current_language = 'en'
 
# tell the theme which language to we're currently building
html_context['current_language'] = current_language
 
# SET CURRENT_VERSION
from git import Repo
repo = Repo( search_parent_directories=True )
 
if 'current_version' in os.environ:
   # get the current_version env var set by buildDocs.sh
   current_version = os.environ['current_version']
else:
   # the user is probably doing `make html`
   # set this build's current version by looking at the branch
   current_version = repo.active_branch.name
 
# tell the theme which version we're currently on ('current_version' affects
# the lower-left rtd menu and 'version' affects the logo-area version)
html_context['current_version'] = current_version
html_context['version'] = current_version
 
# POPULATE LINKS TO OTHER LANGUAGES
html_context['languages'] = [ ('en', '/' +REPO_NAME+ '/en/' +current_version+ '/') ]
 
languages = [lang.name for lang in os.scandir('locales') if lang.is_dir()]
for lang in languages:
   html_context['languages'].append( (lang, '/' +REPO_NAME+ '/' +lang+ '/' +current_version+ '/') )
 
# POPULATE LINKS TO OTHER VERSIONS
html_context['versions'] = list()
 
versions = [branch.name for branch in repo.branches]
for version in versions:
   html_context['versions'].append( (version, '/' +REPO_NAME+ '/'  +current_language+ '/' +version+ '/') )
 
# POPULATE LINKS TO OTHER FORMATS/DOWNLOADS
 
# settings for creating PDF with rinoh
rinoh_documents = [(
 master_doc,
 'target',
 project+ ' Documentation',
 '© ' +copyright,
)]
today_fmt = "%B %d, %Y"
 
# settings for EPUB
epub_basename = 'target'
 
html_context['downloads'] = list()
html_context['downloads'].append( ('pdf', '/' +REPO_NAME+ '/' +current_language+ '/' +current_version+ '/' +project+ '-docs_' +current_language+ '_' +current_version+ '.pdf') )
 
html_context['downloads'].append( ('epub', '/' +REPO_NAME+ '/' +current_language+ '/' +current_version+ '/' +project+ '-docs_' +current_language+ '_' +current_version+ '.epub') )
 
EOF

    See this site for an example:

    The whole config to create the above site can be viewed (and easily forked) from the following GitHub repo:

    For more information on how I set this up, see this article on how to setup the lower-left Read the Docs menu for navigation between languages and versions and downloads.