Read the Docs data passed to Sphinx build context

Before calling sphinx-build to render your docs, Read the Docs injects some extra context in the templates by using the html_context Sphinx setting in the conf.py file. This extra context can be used to build some awesome features in your own theme.

Warning

This design document details future features that are not yet implemented. To discuss this document, please get in touch in the issue tracker.

Note

The Read the Docs Sphinx Theme uses this context to add additional features to the built documentation.

Context injected

Here is the full list of values injected by Read the Docs as a Python dictionary. Note that this dictionary is injected under the main key readthedocs:

{
    "readthedocs": {
        "v1": {
            "version": {
                "id": int,
                "slug": str,
                "verbose_name": str,
                "identifier": str,
                "type": str,
                "build_date": str,
                "downloads": {"pdf": str, "htmlzip": str, "epub": str},
                "links": [
                    {
                        "href": "https://readthedocs.org/api/v2/version/{id}/",
                        "rel": "self",
                    }
                ],
            },
            "project": {
                "id": int,
                "name": str,
                "slug": str,
                "description": str,
                "language": str,
                "canonical_url": str,
                "subprojects": [
                    {
                        "id": int,
                        "name": str,
                        "slug": str,
                        "description": str,
                        "language": str,
                        "canonical_url": str,
                        "links": [
                            {
                                "href": "https://readthedocs.org/api/v2/project/{id}/",
                                "rel": "self",
                            }
                        ],
                    }
                ],
                "links": [
                    {
                        "href": "https://readthedocs.org/api/v2/project/{id}/",
                        "rel": "self",
                    }
                ],
            },
            "sphinx": {"html_theme": str, "source_suffix": str},
            "analytics": {"user_analytics_code": str, "global_analytics_code": str},
            "vcs": {
                "type": str,  # 'bitbucket', 'github', 'gitlab' or 'svn'
                "user": str,
                "repo": str,
                "commit": str,
                "version": str,
                "display": bool,
                "conf_py_path": str,
            },
            "meta": {
                "API_HOST": str,
                "MEDIA_URL": str,
                "PRODUCTION_DOMAIN": str,
                "READTHEDOCS": True,
            },
        }
    }
}

Warning

Read the Docs passes information to sphinx-build that may change in the future (e.g. at the moment of building the version 0.6 this was the latest but then 0.7 and 0.8 were added to the project and also built under Read the Docs) so it’s your responsibility to use this context in a proper way.

In case you want fresh data at the moment of reading your documentation, you should consider using the Read the Docs Public API via Javascript.

Using Read the Docs context in your theme

In case you want to access to this data from your theme, you can use it like this:

{% if readthedocs.v1.vcs.type == 'github' %}
    <a href="https://github.com/{{ readthedocs.v1.vcs.user }}/{{ readthedocs.v1.vcs.repo }}
    /blob/{{ readthedocs.v1.vcs.version }}{{ readthedocs.v1.vcs.conf_py_path }}{{ pagename }}.rst">
    Show on GitHub</a>
{% endif %}

Note

In this example, we are using pagename which is a Sphinx variable representing the name of the page you are on. More information about Sphinx variables can be found in the Sphinx documentation.

Customizing the context

In case you want to add some extra context you will have to declare your own html_context in your conf.py like this:

html_context = {
    "author": "My Name",
    "date": datetime.date.today().strftime("%d/%m/%y"),
}

and use it inside your theme as:

<p>This documentation was written by {{ author }} on {{ date }}.</p>

Warning

Take into account that the Read the Docs context is injected after your definition of html_context so, it’s not possible to override Read the Docs context values.