Enable versions in sidebar in sphinx read the docs theme

Question

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.

Kozak

Are you talking about that little pop-up in the lower-left corner here? docs.readthedocs.io/en/latest Are you using the RTD theme? – Ault

Yes, exactly. But self hosted not on rtd website – Kozak

After rendering, check the browser's developer tools to see if anything gets blocked. If everything loads, does the rendered HTML code, as well as the JS and CSS assets, align with the example of RTD? If not, then you might need to install RTD locally because this might be specific to that environment. Source code: github.com/rtfd/readthedocs.org – Ault

Thanks. I have been looking to the source code of the rendered page and it does not seem to include the sidebar. So, I would think it's rather a sphinx or theme issue. – Kozak

Since it is not including the sidebar, then logically this feature requires that you install the readthedocs.org application, as it is the only missing piece to your system. That is, of course, you have something else terribly wrong, but I doubt it if you can otherwise build your docs successfully. Sphinx itself can generate only one version of documentation at a time, regardless of the theme. – Ault

apparently, it doesn't seem to be possible. There was a pull request for this but it did not get merged. – Kozak

Fork it, create a new feature branch, and pull in the changes from the PR to your local feature branch. Done! – Ault

Answer 1

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:

• https://maltfield.github.io/rtd-github-pages/

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

• https://github.com/maltfield/rtd-github-pages/

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.

Fireresistant

nice, it worked well. I edited the conf.py to add the missing templates declaration – Kozak

I followed the above article, but when I build doc in readthedocs, I get TypeError: HEAD is a detached symbolic reference as it points to 'xyz'. Can you please suggest me? In my local index.html, when I click the dev branch, I get invalid URL error. – Walz

@Walz did you try to fork the repo? github.com/maltfield/rtd-github-pages – Fireresistant

No, i initially followed your article part 1 and 2, and when readthedocs builds, i see the typeerror and build fails. And i just followed this post, by creating versions.html and updating conf.py, still build fails. However, in the terminal, it says main branch is up to date. I had also pinged you in Slack and added you as contributor to my repo. I dint fork the entire repo as i only wanted to implement the versions drop-down. – Declass

Answer 2

If the solution above doesn't pan out for anyone I was able to use this extension to add versioning. sphinx-multiversion. My documentation set up is sphinx with the read-the-docs-theme with private repo for docs on Azure Dev Ops. Same results with this as code snippet above. Refer to the Installation, Quickstart, Configuration and Templates pages for all the working parts.

Realism