diff --git a/docs/design/theme-context.rst b/docs/design/theme-context.rst new file mode 100644 index 00000000000..5c959a1e36a --- /dev/null +++ b/docs/design/theme-context.rst @@ -0,0 +1,156 @@ +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. + +.. _html_context Sphinx setting: http://www.sphinx-doc.org/en/stable/config.html#confval-html_context + +.. note:: + + The `Read the Docs Sphinx Theme`_ uses this context to add additional features to the built documentation. + +.. _Read the Docs Sphinx Theme: https://sphinx-rtd-theme.readthedocs.io/en/latest/ + +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`: + + +.. This context comes from ``readthedocs.doc_builder.backends.sphinx.BaseSphinx.get_config_params`` class. + The source code is at, https://github.com/rtfd/readthedocs.org/blob/0c547f47fb9dffbeb17e4e9ccf205a10caf31189/readthedocs/doc_builder/backends/sphinx.py#L65 + +.. code:: python + + '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 :doc:`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: + +.. code:: html + + {% if readthedocs.v1.vcs.type == 'github' %} + + Show on GitHub + {% 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`_. + + +.. _`Sphinx documentation`: http://www.sphinx-doc.org/en/stable/templating.html#global-variables + + +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: + +.. code:: python + + html_context = { + 'author': 'My Name', + 'date': datetime.date.today().strftime('%d/%m/%y'), + } + +and use it inside your theme as: + +.. code:: html + +

This documentation was written by {{ author }} on {{ date }}.

+ + +.. 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. diff --git a/docs/vcs.rst b/docs/vcs.rst index 8ee07b4d101..4a1f2cd326b 100644 --- a/docs/vcs.rst +++ b/docs/vcs.rst @@ -1,9 +1,15 @@ Version Control System Integration ================================== -If you want to integrate editing into your own theme, you will have to declare -few variables inside your configuration file ``conf.py`` in the ``'html_context'`` -setting, for the template to use them. +.. note:: + + We :doc:`plan to implement a new approach ` regarding the Theme Context as a whole, + although the VCS documentation page will still be valid, we prefer the users to move in that direction. + + +If you want to integrate editing into your own theme, you will have to declare +few variables inside your configuration file ``conf.py`` in the ``'html_context'`` +setting, for the template to use them. More information can be found on `Sphinx documentation`_. @@ -12,7 +18,7 @@ More information can be found on `Sphinx documentation`_. GitHub ------ -If you want to integrate GitHub, you can put the following snippet into +If you want to integrate GitHub, you can put the following snippet into your ``conf.py``:: html_context = { @@ -34,7 +40,7 @@ It can be used like this:: Bitbucket --------- -If you want to integrate Bitbucket, you can put the following snippet into +If you want to integrate Bitbucket, you can put the following snippet into your ``conf.py``:: html_context = { @@ -49,14 +55,14 @@ It can be used like this:: {% if display_bitbucket %} Edit on Bitbucket {% endif %} Gitlab ------ -If you want to integrate Gitlab, you can put the following snippet into +If you want to integrate Gitlab, you can put the following snippet into your ``conf.py``:: html_context = { @@ -72,7 +78,7 @@ It can be used like this:: {% if display_gitlab %} + {{ conf_py_path }}{{ pagename }}{{ suffix }}" class="fa fa-gitlab"> Edit on GitLab {% endif %}