HTML Context API¶

The following Jinja2 context variables are exposed in the Sphinx HTML builder context in all versions.

Versions Iterable¶

versions is the main variable of interest. It yields names of other (and the current) versions and relative URLs to them. You can iterate on it to get all branches and tags, or use special properties attached to it to yield just branches or just tags.

versions¶

An iterable that yields 2-item tuples of strings. The first item is the version (branch/tag) name while the second item is the relative path to the documentation for that version. The path is URL safe and takes into account HTML pages in sub directories.

{%- for name, url in versions %}
    <li><a href="{{ url }}">{{ name }}</a></li>
{%- endfor %}

versions.branches¶

The versions iterable has a branches property that itself yields versions in branches (filtering out git tags). The order is the same and it yields the same tuples.

<dl>
    <dt>Branches</dt>
    {%- for name, url in versions.branches %}
    <dd><a href="{{ url }}">{{ name }}</a></dd>
    {%- endfor %}
</dl>

versions.tags¶

The versions iterable also has a tags property that itself yields versions in tags (filtering out git branches). Just as the branches property the order is maintained and the yielded tuples are the same.

<dl>
    <dt>Tags</dt>
    {%- for name, url in versions.tags %}
    <dd><a href="{{ url }}">{{ name }}</a></dd>
    {%- endfor %}
</dl>

Functions¶

vhasdoc(other_version)¶

Similar to Sphinx’s hasdoc() function. Returns True if the current document exists in another version.

{% if vhasdoc('master') %}
    This doc is available in <a href="../master/index.html">master</a>.
{% endif %}

vpathto(other_version)¶

Similar to Sphinx’s pathto() function. Has two behaviors:

If the current document exists in the specified other version pathto() returns the relative URL to that document.
If the current document does not exist in the other version the relative URL to that version’s master_doc is returned instead.

{% if vhasdoc('master') %}
    This doc is available in <a href="{{ vpathto('master') }}">master</a>.
{% else %}
    Go to <a href="{{ vpathto('master') }}">master</a> for the latest docs.
{% endif %}

Banner Variables¶

These variables are exposed in the Jinja2 context to facilitate displaying the banner message and deciding which message to display.

scv_banner_greatest_tag¶: A boolean set to True if --banner-greatest-tag is used.

scv_banner_main_ref_is_branch¶: A boolean set to True if the banner main ref is a branch.

scv_banner_main_ref_is_tag¶: A boolean set to True if the banner main ref is a tag.

scv_banner_main_version¶: A string, the value of --banner-main-ref.

scv_banner_recent_tag¶: A boolean set to True if --banner-recent-tag is used.

scv_show_banner¶: A boolean set to True if --show-banner is used.

Other Variables¶

current_version¶

A string of the current version being built. This will be the git ref name (e.g. a branch name or tag name).

<h3>Current Version: {{ current_version }}</h3>

scv_is_branch¶: A boolean set to True if the current version being built is from a git branch.

scv_is_greatest_tag¶

A boolean set to True if the current version being built is:

From a git tag.
A valid semver-formatted name (e.g. v1.2.3).
The highest version number.

scv_is_recent_branch¶: A boolean set to True if the current version being built is a git branch and is the most recent commit out of just git branches.

scv_is_recent_ref¶: A boolean set to True if the current version being built is the most recent git commit (branch or tag).

scv_is_recent_tag¶: A boolean set to True if the current version being built is a git tag and is the most recent commit out of just git tags.

scv_is_root¶: A boolean set to True if the current version being built is in the web root (defined by --root-ref).

scv_is_tag¶: A boolean set to True if the current version being built is from a git tag.