Skip to content

Commit c5d102a

Browse files
humitosagjohnson
humitos
authored and
agjohnson
committed
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 index
1 parent 3c674f0 commit c5d102a

File tree

2 files changed

+170
-8
lines changed

2 files changed

+170
-8
lines changed

‎docs/design/theme-context.rst

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
Read the Docs data passed to Sphinx build context
2+
=================================================
3+
4+
Before calling `sphinx-build` to render your docs, Read the Docs injects some
5+
extra context in the templates by using the `html_context Sphinx setting`_ in the ``conf.py`` file.
6+
This extra context can be used to build some awesome features in your own theme.
7+
8+
.. _html_context Sphinx setting: http://www.sphinx-doc.org/en/stable/config.html#confval-html_context
9+
10+
.. note::
11+
12+
The `Read the Docs Sphinx Theme`_ uses this context to add additional features to the built documentation.
13+
14+
.. _Read the Docs Sphinx Theme: https://sphinx-rtd-theme.readthedocs.io/en/latest/
15+
16+
Context injected
17+
----------------
18+
19+
Here is the full list of values injected by Read the Docs as a Python dictionary.
20+
Note that this dictionary is injected under the main key `readthedocs`:
21+
22+
23+
.. This context comes from ``readthedocs.doc_builder.backends.sphinx.BaseSphinx.get_config_params`` class.
24+
The source code is at, https://github.com/rtfd/readthedocs.org/blob/0c547f47fb9dffbeb17e4e9ccf205a10caf31189/readthedocs/doc_builder/backends/sphinx.py#L65
25+
26+
.. code:: python
27+
28+
'readthedocs': {
29+
'v1': {
30+
'version': {
31+
'id': int,
32+
'slug': str,
33+
'verbose_name': str,
34+
'identifier': str,
35+
'type': str,
36+
'build_date': str,
37+
'downloads': {
38+
'pdf: str,
39+
'htmlzip': str,
40+
'epub': str
41+
},
42+
'links': [{
43+
'href': 'https://readthedocs.org/api/v2/version/{id}/',
44+
'rel': 'self
45+
}]
46+
},
47+
'project': {
48+
'id': int
49+
'name': str,
50+
'slug': str,
51+
'description': str,
52+
'language': str,
53+
'canonical_url': str,
54+
'subprojects': [{
55+
'id': int
56+
'name': str,
57+
'slug': str,
58+
'description': str,
59+
'language': str,
60+
'canonical_url': str,
61+
'links': [{
62+
'href': 'https://readthedocs.org/api/v2/project/{id}/',
63+
'rel': 'self
64+
}]
65+
}],
66+
'links': [{
67+
'href': 'https://readthedocs.org/api/v2/project/{id}/',
68+
'rel': 'self
69+
}]
70+
},
71+
'sphinx': {
72+
'html_theme': str,
73+
'source_suffix': str
74+
},
75+
'analytics': {
76+
'user_analytics_code': str,
77+
'global_analytics_code': str
78+
},
79+
'vcs': {
80+
'type': str, # 'bitbucket', 'github', 'gitlab' or 'svn'
81+
'user': str,
82+
'repo': str,
83+
'commit': str,
84+
'version': str,
85+
'display': bool,
86+
'conf_py_path': str
87+
},
88+
'meta': {
89+
'API_HOST': str,
90+
'MEDIA_URL': str,
91+
'PRODUCTION_DOMAIN': str,
92+
'READTHEDOCS': True
93+
}
94+
}
95+
}
96+
97+
98+
.. warning::
99+
100+
Read the Docs passes information to `sphinx-build` that may change in the future
101+
(e.g. at the moment of building the version `0.6` this was the `latest`
102+
but then `0.7` and `0.8` were added to the project and also built under Read the Docs)
103+
so it's your responsibility to use this context in a proper way.
104+
105+
In case you want *fresh data* at the moment of reading your documentation,
106+
you should consider using the :doc:`Read the Docs Public API <api>` via Javascript.
107+
108+
109+
Using Read the Docs context in your theme
110+
-----------------------------------------
111+
112+
In case you want to access to this data from your theme, you can use it like this:
113+
114+
.. code:: html
115+
116+
{% if readthedocs.v1.vcs.type == 'github' %}
117+
<a href="https://github.com/{{ readthedocs.v1.vcs.user }}/{{ readthedocs.v1.vcs.repo }}
118+
/blob/{{ readthedocs.v1.vcs.version }}{{ readthedocs.v1.vcs.conf_py_path }}{{ pagename }}.rst">
119+
Show on GitHub</a>
120+
{% endif %}
121+
122+
123+
.. note::
124+
125+
In this example, we are using ``pagename`` which is a Sphinx variable
126+
representing the name of the page you are on. More information about Sphinx
127+
variables can be found in the `Sphinx documentation`_.
128+
129+
130+
.. _`Sphinx documentation`: http://www.sphinx-doc.org/en/stable/templating.html#global-variables
131+
132+
133+
Customizing the context
134+
-----------------------
135+
136+
In case you want to add some extra context you will have to declare your own
137+
``html_context`` in your ``conf.py`` like this:
138+
139+
.. code:: python
140+
141+
html_context = {
142+
'author': 'My Name',
143+
'date': datetime.date.today().strftime('%d/%m/%y'),
144+
}
145+
146+
and use it inside your theme as:
147+
148+
.. code:: html
149+
150+
<p>This documentation was written by {{ author }} on {{ date }}.</p>
151+
152+
153+
.. warning::
154+
155+
Take into account that the Read the Docs context is injected after your definition of ``html_context`` so,
156+
it's not possible to override Read the Docs context values.

‎docs/vcs.rst

Lines changed: 14 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,15 @@
11
Version Control System Integration
22
==================================
33

4-
If you want to integrate editing into your own theme, you will have to declare
5-
few variables inside your configuration file ``conf.py`` in the ``'html_context'``
6-
setting, for the template to use them.
4+
.. note::
5+
6+
We :doc:`plan to implement a new approach <design/theme-context>` regarding the Theme Context as a whole,
7+
although the VCS documentation page will still be valid, we prefer the users to move in that direction.
8+
9+
10+
If you want to integrate editing into your own theme, you will have to declare
11+
few variables inside your configuration file ``conf.py`` in the ``'html_context'``
12+
setting, for the template to use them.
713

814
More information can be found on `Sphinx documentation`_.
915

@@ -12,7 +18,7 @@ More information can be found on `Sphinx documentation`_.
1218
GitHub
1319
------
1420

15-
If you want to integrate GitHub, you can put the following snippet into
21+
If you want to integrate GitHub, you can put the following snippet into
1622
your ``conf.py``::
1723

1824
html_context = {
@@ -34,7 +40,7 @@ It can be used like this::
3440
Bitbucket
3541
---------
3642

37-
If you want to integrate Bitbucket, you can put the following snippet into
43+
If you want to integrate Bitbucket, you can put the following snippet into
3844
your ``conf.py``::
3945

4046
html_context = {
@@ -49,14 +55,14 @@ It can be used like this::
4955

5056
{% if display_bitbucket %}
5157
<a href="https://bitbucket.org/{{ bitbucket_user }}/{{ bitbucket_repo }}
52-
/src/{{ bitbucket_version}}{{ conf_py_path }}{{ pagename }}.rst'"
58+
/src/{{ bitbucket_version}}{{ conf_py_path }}{{ pagename }}.rst'"
5359
class="icon icon-bitbucket"> Edit on Bitbucket</a>
5460
{% endif %}
5561

5662
Gitlab
5763
------
5864

59-
If you want to integrate Gitlab, you can put the following snippet into
65+
If you want to integrate Gitlab, you can put the following snippet into
6066
your ``conf.py``::
6167

6268
html_context = {
@@ -72,7 +78,7 @@ It can be used like this::
7278
{% if display_gitlab %}
7379
<a href="https://{{ gitlab_host|default("gitlab.com") }}/
7480
{{ gitlab_user }}/{{ gitlab_repo }}/blob/{{ gitlab_version }}
75-
{{ conf_py_path }}{{ pagename }}{{ suffix }}" class="fa fa-gitlab">
81+
{{ conf_py_path }}{{ pagename }}{{ suffix }}" class="fa fa-gitlab">
7682
Edit on GitLab</a>
7783
{% endif %}
7884

0 commit comments

Comments
 (0)