Documentation for RTD context sent to the Sphinx theme (#3490)
* Documentation for RTD context sent to the Sphinx theme * Fix index * Added version downloads * Add `pk` and `resource_uri` to be able to retrieve fresh data * Typos and grammar fixes * Improve context * build_date * HATEOAS for resources * Add v1 namespace and better explanation about static/dynamic data * Update context to follow APIv2 reponses Examples: * http://readthedocs.org/api/v2/project/{id}/ * http://readthedocs.org/api/v2/version/{id}/ * Add subprojects inside project * SVN as an option * Docs: Correct small typo * Add comment saying where this context comes from * Re-add VCS documentation file * Move proposal design under `docs/design/` directory * Cleanup extra spaces * Add note about the new design for the theme context * Update the indexhumitos/resolver/username-regex
Manuel Kaufmann
Anthony
parent
3c674f05ad
commit
c5d102a4b1
|
|
@ -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 <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' %}
|
||||
<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`_.
|
||||
|
||||
|
||||
.. _`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
|
||||
|
||||
<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.
|
||||
22
docs/vcs.rst
22
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 <design/theme-context>` 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 %}
|
||||
<a href="https://bitbucket.org/{{ bitbucket_user }}/{{ bitbucket_repo }}
|
||||
/src/{{ bitbucket_version}}{{ conf_py_path }}{{ pagename }}.rst'"
|
||||
/src/{{ bitbucket_version}}{{ conf_py_path }}{{ pagename }}.rst'"
|
||||
class="icon icon-bitbucket"> Edit on Bitbucket</a>
|
||||
{% 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 %}
|
||||
<a href="https://{{ gitlab_host|default("gitlab.com") }}/
|
||||
{{ gitlab_user }}/{{ gitlab_repo }}/blob/{{ gitlab_version }}
|
||||
{{ conf_py_path }}{{ pagename }}{{ suffix }}" class="fa fa-gitlab">
|
||||
{{ conf_py_path }}{{ pagename }}{{ suffix }}" class="fa fa-gitlab">
|
||||
Edit on GitLab</a>
|
||||
{% endif %}
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue