.. _context: ================ 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. .. attribute:: 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. .. code-block:: jinja {%- for name, url in versions %}
  • {{ name }}
  • {%- endfor %} .. attribute:: 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. .. code-block:: jinja
    Branches
    {%- for name, url in versions.branches %}
    {{ name }}
    {%- endfor %}
    .. attribute:: 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. .. code-block:: jinja
    Tags
    {%- for name, url in versions.tags %}
    {{ name }}
    {%- endfor %}
    Functions ========= .. function:: vhasdoc(other_version) Similar to Sphinx's `hasdoc() `_ function. Returns True if the current document exists in another version. .. code-block:: jinja {% if vhasdoc('master') %} This doc is available in master. {% endif %} .. function:: vpathto(other_version) Similar to Sphinx's `pathto() `_ function. Has two behaviors: 1. If the current document exists in the specified other version pathto() returns the relative URL to that document. 2. If the current document does not exist in the other version the relative URL to that version's `master_doc `_ is returned instead. .. code-block:: jinja {% if vhasdoc('master') %} This doc is available in master. {% else %} Go to master 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. .. attribute:: scv_banner_greatest_tag A boolean set to True if :option:`--banner-greatest-tag` is used. .. attribute:: scv_banner_main_ref_is_branch A boolean set to True if the banner main ref is a branch. .. attribute:: scv_banner_main_ref_is_tag A boolean set to True if the banner main ref is a tag. .. attribute:: scv_banner_main_version A string, the value of :option:`--banner-main-ref`. .. attribute:: scv_banner_recent_tag A boolean set to True if :option:`--banner-recent-tag` is used. .. attribute:: scv_show_banner A boolean set to True if :option:`--show-banner` is used. Other Variables =============== .. attribute:: 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). .. code-block:: jinja

    Current Version: {{ current_version }}

    .. attribute:: scv_is_branch A boolean set to True if the current version being built is from a git branch. .. attribute:: 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. .. attribute:: 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. .. attribute:: scv_is_recent_ref A boolean set to True if the current version being built is the most recent git commit (branch or tag). .. attribute:: 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. .. attribute:: scv_is_root A boolean set to True if the current version being built is in the web root (defined by :option:`--root-ref`). .. attribute:: scv_is_tag A boolean set to True if the current version being built is from a git tag. .. _Jinja2: http://jinja.pocoo.org/ .. _sphinx_context: http://www.sphinx-doc.org/en/stable/config.html?highlight=context#confval-html_context .. _sphinx_hasdoc: http://www.sphinx-doc.org/en/stable/templating.html#hasdoc .. _sphinx_master_doc: http://www.sphinx-doc.org/en/stable/config.html#confval-master_doc .. _sphinx_pathto: http://www.sphinx-doc.org/en/stable/templating.html#pathto