sphinx-multiversion
does not change the look of your HTML output by default. Instead, you can customize the template to cater to your needs.
To add version listings to your template, you need to add a custom template to your theme.
You can take one of the snippets below, put it into _templates/versioning.html
and add it to your theme's sidebar:
templates_path = [
"_templates",
]
html_sidebars = [
"versioning.html",
]
{% if versions %}
<h3>{{ _('Versions') }}</h3>
<ul>
{%- for item in versions %}
<li><a href="{{ item.url }}">{{ item.name }}</a></li>
{%- endfor %}
</ul>
{% endif %}
{% if versions %}
<h3>{{ _('Branches') }}</h3>
<ul>
{%- for item in versions.branches %}
<li><a href="{{ item.url }}">{{ item.name }}</a></li>
{%- endfor %}
</ul>
<h3>{{ _('Tags') }}</h3>
<ul>
{%- for item in versions.tags %}
<li><a href="{{ item.url }}">{{ item.name }}</a></li>
{%- endfor %}
</ul>
{% endif %}
{% if versions %}
<h3>{{ _('Releases') }}</h3>
<ul>
{%- for item in versions.releases %}
<li><a href="{{ item.url }}">{{ item.name }}</a></li>
{%- endfor %}
</ul>
<h3>{{ _('In Development') }}</h3>
<ul>
{%- for item in versions.in_development %}
<li><a href="{{ item.url }}">{{ item.name }}</a></li>
{%- endfor %}
</ul>
{% endif %}
You can also add version banners to your theme, for example:
{% extends "page.html" %}
{% block body %}
{% if current_version and latest_version and current_version != latest_version %}
<p>
<strong>
{% if current_version.is_released %}
You're reading an old version of this documentation.
If you want up-to-date information, please have a look at <a href="{{ vpathto(latest_version.name) }}">{{latest_version.name}}</a>.
{% else %}
You're reading the documentation for a development version.
For the latest released version, please have a look at <a href="{{ vpathto(latest_version.name) }}">{{latest_version.name}}</a>.
{% endif %}
<strong>
</p>
{% endif %}
{{ super() }}
{% endblock %}%
As of version 0.4.3, the Read the Docs theme does not support sidebar widgets. So instead of adding a custom template to html_sidebars
, you need to create a template file named versions.html
with the following content:
{%- if current_version %}
<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"> Other Versions</span>
v: {{ current_version.name }}
<span class="fa fa-caret-down"></span>
</span>
<div class="rst-other-versions">
{%- if versions.tags %}
<dl>
<dt>Tags</dt>
{%- for item in versions.tags %}
<dd><a href="{{ item.url }}">{{ item.name }}</a></dd>
{%- endfor %}
</dl>
{%- endif %}
{%- if versions.branches %}
<dl>
<dt>Branches</dt>
{%- for item in versions.branches %}
<dd><a href="{{ item.url }}">{{ item.name }}</a></dd>
{%- endfor %}
</dl>
{%- endif %}
</div>
</div>
{%- endif %}