From c5041a492bc5a4164624ad097ca3d176074a52f5 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Mon, 8 Jan 2018 19:56:49 -0500 Subject: [PATCH 01/17] Documentation for RTD context sent to the Sphinx theme --- docs/theme-context.rst | 112 +++++++++++++++++++++++++++++++++++++++++ docs/vcs.rst | 82 ------------------------------ 2 files changed, 112 insertions(+), 82 deletions(-) create mode 100644 docs/theme-context.rst delete mode 100644 docs/vcs.rst diff --git a/docs/theme-context.rst b/docs/theme-context.rst new file mode 100644 index 00000000000..4bd0c94c5d5 --- /dev/null +++ b/docs/theme-context.rst @@ -0,0 +1,112 @@ +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 allows Read the Docs to add some +features like "Edit on GitHub" and use a custom Analytics code, among others. + + +Context injected by default +--------------------------- + +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`: + + +.. code:: python + + 'readthedocs': { + 'version': { + 'name': str, + 'slug': str, + 'latest': bool, + 'stable': bool, + }, + 'project': { + 'name': str, + 'slug': str, + 'rtd_language': str, # can be different than language in conf.py + 'canonical_url': str, + 'single_version': bool, + 'versions': [ + { + 'slug': str, + 'href': str + } + ], + 'subprojects': [ + { + 'slug': str, + 'href': str + } + ] + }, + 'build': { + 'html_theme': str, + 'source_suffix': str, + 'api_host': str, + 'user_analytics_code': str, + 'global_analytics_code': str + }, + 'vcs': { + 'type': str, # 'bitbucket', 'github' or 'gitlab' + 'user': str, + 'repo': str, + 'commit': str, + 'version': str, + 'display': bool + 'conf_py_path': str + }, + 'meta': { + 'READTHEDOCS': True, + 'MEDIA_URL': str, + 'PRODUCTION_DOMAIN': str + } + } + + +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.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 on `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 }}.

diff --git a/docs/vcs.rst b/docs/vcs.rst deleted file mode 100644 index 8ee07b4d101..00000000000 --- a/docs/vcs.rst +++ /dev/null @@ -1,82 +0,0 @@ -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. - -More information can be found on `Sphinx documentation`_. - -.. _`Sphinx documentation`: http://www.sphinx-doc.org/en/1.5.2/config.html#confval-html_context - -GitHub ------- - -If you want to integrate GitHub, you can put the following snippet into -your ``conf.py``:: - - html_context = { - "display_github": True, # Integrate GitHub - "github_user": "MyUserName", # Username - "github_repo": "MyDoc", # Repo name - "github_version": "master", # Version - "conf_py_path": "/source/", # Path in the checkout to the docs root - } - -It can be used like this:: - - {% if display_github %} -
  • - Show on GitHub
    • - {% endif %} - -Bitbucket ---------- - -If you want to integrate Bitbucket, you can put the following snippet into -your ``conf.py``:: - - html_context = { - "display_bitbucket": True, # Integrate Bitbucket - "bitbucket_user": "MyUserName", # Username - "bitbucket_repo": "MyDoc", # Repo name - "bitbucket_version": "master", # Version - "conf_py_path": "/source/", # Path in the checkout to the docs root - } - -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 -your ``conf.py``:: - - html_context = { - "display_gitlab": True, # Integrate Gitlab - "gitlab_user": "MyUserName", # Username - "gitlab_repo": "MyDoc", # Repo name - "gitlab_version": "master", # Version - "conf_py_path": "/source/", # Path in the checkout to the docs root - } - -It can be used like this:: - - {% if display_gitlab %} - - Edit on GitLab - {% endif %} - -Additional variables --------------------- - -* ``'pagename'`` - Sphinx variable representing the name of the page you're on. From c77ad573b0a02e0cb4d837a64f805c5d5f84b5d7 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Mon, 8 Jan 2018 20:00:44 -0500 Subject: [PATCH 02/17] Fix index --- docs/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index d6e30f31272..d80a5485cdb 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -76,7 +76,7 @@ Information about development is also available: badges alternate_domains localization - vcs + theme-context subprojects conda canonical From b7426bf93f7b321e10a73c8e45c5a028aa85f334 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Mon, 8 Jan 2018 20:09:55 -0500 Subject: [PATCH 03/17] Added version downloads --- docs/theme-context.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/theme-context.rst b/docs/theme-context.rst index 4bd0c94c5d5..6723e540a3d 100644 --- a/docs/theme-context.rst +++ b/docs/theme-context.rst @@ -23,6 +23,11 @@ dictionary. Note that this dictionary is injected under the main key 'slug': str, 'latest': bool, 'stable': bool, + 'downloads': { + 'pdf: str, + 'htmlzip': str, + 'epub': str + } }, 'project': { 'name': str, From 2bdc191eba557e9db715e511c43eb744675a1015 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Thu, 11 Jan 2018 10:20:40 -0500 Subject: [PATCH 04/17] Add `pk` and `resource_uri` to be able to retrieve fresh data --- docs/theme-context.rst | 54 +++++++++++++++++++++++------------------- 1 file changed, 30 insertions(+), 24 deletions(-) diff --git a/docs/theme-context.rst b/docs/theme-context.rst index 6723e540a3d..f5dd14a5d59 100644 --- a/docs/theme-context.rst +++ b/docs/theme-context.rst @@ -2,10 +2,11 @@ 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 +extra context in the templates by using the `html_context Sphinx setting`_ in the ``conf.py`` file. This extra context allows Read the Docs to add some -features like "Edit on GitHub" and use a custom Analytics code, among others. +features like "Edit on GitHub" and use a user custom Analytics code, among others. +.. _html_context Sphinx setting: http://www.sphinx-doc.org/en/stable/config.html#confval-html_context Context injected by default --------------------------- @@ -19,39 +20,28 @@ dictionary. Note that this dictionary is injected under the main key 'readthedocs': { 'version': { + 'pk': int, 'name': str, 'slug': str, - 'latest': bool, - 'stable': bool, 'downloads': { 'pdf: str, 'htmlzip': str, 'epub': str - } + }, + 'resource_uri': '/api/v2/version/{pk}/' }, 'project': { + 'pk': int 'name': str, 'slug': str, - 'rtd_language': str, # can be different than language in conf.py 'canonical_url': str, - 'single_version': bool, - 'versions': [ - { - 'slug': str, - 'href': str - } - ], - 'subprojects': [ - { - 'slug': str, - 'href': str - } - ] + 'resource_uri': '/api/v2/project/{pk}/' }, - 'build': { + 'sphinx': { 'html_theme': str, 'source_suffix': str, - 'api_host': str, + }, + 'analytics': { 'user_analytics_code': str, 'global_analytics_code': str }, @@ -61,17 +51,27 @@ dictionary. Note that this dictionary is injected under the main key 'repo': str, 'commit': str, 'version': str, - 'display': bool + 'display': bool, 'conf_py_path': str }, 'meta': { - 'READTHEDOCS': True, + 'API_HOST': str, 'MEDIA_URL': str, - 'PRODUCTION_DOMAIN': str + 'PRODUCTION_DOMAIN': str, + 'READTHEDOCS': True } } +.. note:: + + By design, Read the Docs passes only static information to `sphinx-build` + to avoid versions to be inconsistent in case the project is updated after the version is built. + In case you need more information than the context supplied here, you will + need to use :doc:`Read the Docs Public API ` to retrieve fresh data about the project + (e.g. know if the current version is the `latest` or `stable`, get all versions of a project, etc). + + Using Read the Docs context in your theme ----------------------------------------- @@ -115,3 +115,9 @@ and use it inside your theme as: .. code:: html

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

    + + +.. note:: + + Take into account that the Read the Docs context is inject after your definition of ``html_context`` so, + it's not possible to override Read the Docs context values. From 17f1055c27b053d823a5b64334cc20f9cc3e777b Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Mon, 15 Jan 2018 09:53:46 -0500 Subject: [PATCH 05/17] Typos and grammar fixes --- docs/theme-context.rst | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/docs/theme-context.rst b/docs/theme-context.rst index f5dd14a5d59..203bd8a6bb4 100644 --- a/docs/theme-context.rst +++ b/docs/theme-context.rst @@ -3,17 +3,16 @@ 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 allows Read the Docs to add some -features like "Edit on GitHub" and use a user custom Analytics code, among others. +the ``conf.py`` file. This extra context is used by the Read the Docs Sphinx Theme +to add additional features to the built documentation .. _html_context Sphinx setting: http://www.sphinx-doc.org/en/stable/config.html#confval-html_context -Context injected by default ---------------------------- +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`: +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`: .. code:: python @@ -67,7 +66,7 @@ dictionary. Note that this dictionary is injected under the main key By design, Read the Docs passes only static information to `sphinx-build` to avoid versions to be inconsistent in case the project is updated after the version is built. - In case you need more information than the context supplied here, you will + In case you need more information than the context supplies here, you will need to use :doc:`Read the Docs Public API ` to retrieve fresh data about the project (e.g. know if the current version is the `latest` or `stable`, get all versions of a project, etc). @@ -75,8 +74,7 @@ dictionary. Note that this dictionary is injected under the main key 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: +In case you want to access to this data from your theme, you can use it like this: .. code:: html @@ -119,5 +117,5 @@ and use it inside your theme as: .. note:: - Take into account that the Read the Docs context is inject after your definition of ``html_context`` so, + 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. From 6b82f0e62f90c77dc198515f94fd85a14eed9468 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Mon, 15 Jan 2018 20:02:51 -0500 Subject: [PATCH 06/17] Improve context * build_date * HATEOAS for resources --- docs/theme-context.rst | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/theme-context.rst b/docs/theme-context.rst index 203bd8a6bb4..f0f84716265 100644 --- a/docs/theme-context.rst +++ b/docs/theme-context.rst @@ -22,19 +22,26 @@ Note that this dictionary is injected under the main key `readthedocs`: 'pk': int, 'name': str, 'slug': str, + 'build_date': str, 'downloads': { 'pdf: str, 'htmlzip': str, 'epub': str }, - 'resource_uri': '/api/v2/version/{pk}/' + 'links': [{ + 'href': 'https://readthedocs.org/api/v2/version/{pk}/', + 'rel': 'self + }], }, 'project': { 'pk': int 'name': str, 'slug': str, 'canonical_url': str, - 'resource_uri': '/api/v2/project/{pk}/' + 'links': [{ + 'href': 'https://readthedocs.org/api/v2/project/{pk}/', + 'rel': 'self + }], }, 'sphinx': { 'html_theme': str, @@ -115,7 +122,7 @@ and use it inside your theme as:

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

    -.. note:: +.. 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. From 540acd9d18c21772139c31a80345aa4a01689e40 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Tue, 16 Jan 2018 10:27:00 -0500 Subject: [PATCH 07/17] Add v1 namespace and better explanation about static/dynamic data --- docs/theme-context.rst | 125 ++++++++++++++++++++++------------------- 1 file changed, 67 insertions(+), 58 deletions(-) diff --git a/docs/theme-context.rst b/docs/theme-context.rst index f0f84716265..e27ac2bfe59 100644 --- a/docs/theme-context.rst +++ b/docs/theme-context.rst @@ -2,12 +2,17 @@ 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 is used by the Read the Docs Sphinx Theme -to add additional features to the built documentation +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 ---------------- @@ -18,64 +23,68 @@ Note that this dictionary is injected under the main key `readthedocs`: .. code:: python 'readthedocs': { - 'version': { - 'pk': int, - 'name': str, - 'slug': str, - 'build_date': str, - 'downloads': { - 'pdf: str, - 'htmlzip': str, - 'epub': str + 'v1': { + 'version': { + 'pk': int, + 'name': str, + 'slug': str, + 'build_date': str, + 'downloads': { + 'pdf: str, + 'htmlzip': str, + 'epub': str + }, + 'links': [{ + 'href': 'https://readthedocs.org/api/v2/version/{pk}/', + 'rel': 'self + }], + }, + 'project': { + 'pk': int + 'name': str, + 'slug': str, + 'canonical_url': str, + 'links': [{ + 'href': 'https://readthedocs.org/api/v2/project/{pk}/', + 'rel': 'self + }], + }, + 'sphinx': { + 'html_theme': str, + 'source_suffix': str, }, - 'links': [{ - 'href': 'https://readthedocs.org/api/v2/version/{pk}/', - 'rel': 'self - }], - }, - 'project': { - 'pk': int - 'name': str, - 'slug': str, - 'canonical_url': str, - 'links': [{ - 'href': 'https://readthedocs.org/api/v2/project/{pk}/', - 'rel': 'self - }], - }, - 'sphinx': { - 'html_theme': str, - 'source_suffix': str, - }, - 'analytics': { - 'user_analytics_code': str, - 'global_analytics_code': str - }, - 'vcs': { - 'type': str, # 'bitbucket', 'github' or 'gitlab' - '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 + 'analytics': { + 'user_analytics_code': str, + 'global_analytics_code': str + }, + 'vcs': { + 'type': str, # 'bitbucket', 'github' or 'gitlab' + '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 + } } } -.. note:: +.. 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. - By design, Read the Docs passes only static information to `sphinx-build` - to avoid versions to be inconsistent in case the project is updated after the version is built. - In case you need more information than the context supplies here, you will - need to use :doc:`Read the Docs Public API ` to retrieve fresh data about the project - (e.g. know if the current version is the `latest` or `stable`, get all versions of a project, etc). + 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 @@ -85,9 +94,9 @@ In case you want to access to this data from your theme, you can use it like thi .. code:: html - {% if readthedocs.vcs.type == 'github' %} - + {% if readthedocs.v1.vcs.type == 'github' %} + Show on GitHub {% endif %} From 1a61cc8bc16cb7a2c0e3df638dae19c7b61efeba Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Tue, 16 Jan 2018 10:31:55 -0500 Subject: [PATCH 08/17] Update context to follow APIv2 reponses Examples: * http://readthedocs.org/api/v2/project/{id}/ * http://readthedocs.org/api/v2/version/{id}/ --- docs/theme-context.rst | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/docs/theme-context.rst b/docs/theme-context.rst index e27ac2bfe59..5a0b953f531 100644 --- a/docs/theme-context.rst +++ b/docs/theme-context.rst @@ -25,9 +25,11 @@ Note that this dictionary is injected under the main key `readthedocs`: 'readthedocs': { 'v1': { 'version': { - 'pk': int, - 'name': str, + 'id': int, 'slug': str, + 'verbose_name': str, + 'identifier': str, + 'type': str, 'build_date': str, 'downloads': { 'pdf: str, @@ -35,23 +37,25 @@ Note that this dictionary is injected under the main key `readthedocs`: 'epub': str }, 'links': [{ - 'href': 'https://readthedocs.org/api/v2/version/{pk}/', + 'href': 'https://readthedocs.org/api/v2/version/{id}/', 'rel': 'self - }], + }] }, 'project': { - 'pk': int + 'id': int 'name': str, 'slug': str, + 'description': str, + 'language': str, 'canonical_url': str, 'links': [{ - 'href': 'https://readthedocs.org/api/v2/project/{pk}/', + 'href': 'https://readthedocs.org/api/v2/project/{id}/', 'rel': 'self - }], + }] }, 'sphinx': { 'html_theme': str, - 'source_suffix': str, + 'source_suffix': str }, 'analytics': { 'user_analytics_code': str, From d378093f7af9f44be2764ea966fac905a1fda369 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Tue, 16 Jan 2018 10:45:08 -0500 Subject: [PATCH 09/17] Add subprojects inside project --- docs/theme-context.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/theme-context.rst b/docs/theme-context.rst index 5a0b953f531..29621d66159 100644 --- a/docs/theme-context.rst +++ b/docs/theme-context.rst @@ -48,6 +48,18 @@ Note that this dictionary is injected under the main key `readthedocs`: '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 From c60671f1cf9e45966f6fb93f203a4f580e54080c Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Tue, 16 Jan 2018 10:45:18 -0500 Subject: [PATCH 10/17] SVN as an option --- docs/theme-context.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/theme-context.rst b/docs/theme-context.rst index 29621d66159..176e784cf89 100644 --- a/docs/theme-context.rst +++ b/docs/theme-context.rst @@ -74,7 +74,7 @@ Note that this dictionary is injected under the main key `readthedocs`: 'global_analytics_code': str }, 'vcs': { - 'type': str, # 'bitbucket', 'github' or 'gitlab' + 'type': str, # 'bitbucket', 'github', 'gitlab' or 'svn' 'user': str, 'repo': str, 'commit': str, From d1aaede580f23ce6dea04684fc6ff5df326e836c Mon Sep 17 00:00:00 2001 From: Aaron Carlisle Date: Thu, 8 Feb 2018 09:19:48 -0500 Subject: [PATCH 11/17] Docs: Correct small typo --- docs/theme-context.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/theme-context.rst b/docs/theme-context.rst index 176e784cf89..516b2e26e4a 100644 --- a/docs/theme-context.rst +++ b/docs/theme-context.rst @@ -121,7 +121,7 @@ In case you want to access to this data from your theme, you can use it like thi 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 on `Sphinx documentation`_. + variables can be found in the `Sphinx documentation`_. .. _`Sphinx documentation`: http://www.sphinx-doc.org/en/stable/templating.html#global-variables From bf3f75e906df5c6724c4d897b7e441a995104f4d Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Tue, 20 Feb 2018 12:08:08 -0500 Subject: [PATCH 12/17] Add comment saying where this context comes from --- docs/theme-context.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/theme-context.rst b/docs/theme-context.rst index 516b2e26e4a..5c959a1e36a 100644 --- a/docs/theme-context.rst +++ b/docs/theme-context.rst @@ -20,6 +20,9 @@ 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': { From d138e33e361f4ab2e82775c5f961f2f451aef714 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Thu, 22 Mar 2018 13:53:39 -0500 Subject: [PATCH 13/17] Re-add VCS documentation file --- docs/vcs.rst | 82 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 82 insertions(+) create mode 100644 docs/vcs.rst diff --git a/docs/vcs.rst b/docs/vcs.rst new file mode 100644 index 00000000000..8ee07b4d101 --- /dev/null +++ b/docs/vcs.rst @@ -0,0 +1,82 @@ +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. + +More information can be found on `Sphinx documentation`_. + +.. _`Sphinx documentation`: http://www.sphinx-doc.org/en/1.5.2/config.html#confval-html_context + +GitHub +------ + +If you want to integrate GitHub, you can put the following snippet into +your ``conf.py``:: + + html_context = { + "display_github": True, # Integrate GitHub + "github_user": "MyUserName", # Username + "github_repo": "MyDoc", # Repo name + "github_version": "master", # Version + "conf_py_path": "/source/", # Path in the checkout to the docs root + } + +It can be used like this:: + + {% if display_github %} +
  • + Show on GitHub
    • + {% endif %} + +Bitbucket +--------- + +If you want to integrate Bitbucket, you can put the following snippet into +your ``conf.py``:: + + html_context = { + "display_bitbucket": True, # Integrate Bitbucket + "bitbucket_user": "MyUserName", # Username + "bitbucket_repo": "MyDoc", # Repo name + "bitbucket_version": "master", # Version + "conf_py_path": "/source/", # Path in the checkout to the docs root + } + +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 +your ``conf.py``:: + + html_context = { + "display_gitlab": True, # Integrate Gitlab + "gitlab_user": "MyUserName", # Username + "gitlab_repo": "MyDoc", # Repo name + "gitlab_version": "master", # Version + "conf_py_path": "/source/", # Path in the checkout to the docs root + } + +It can be used like this:: + + {% if display_gitlab %} + + Edit on GitLab + {% endif %} + +Additional variables +-------------------- + +* ``'pagename'`` - Sphinx variable representing the name of the page you're on. From fb86162e6d45c9b2a2bb962b9221e16da7a79ad7 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Thu, 22 Mar 2018 13:54:29 -0500 Subject: [PATCH 14/17] Move proposal design under `docs/design/` directory --- docs/{ => design}/theme-context.rst | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{ => design}/theme-context.rst (100%) diff --git a/docs/theme-context.rst b/docs/design/theme-context.rst similarity index 100% rename from docs/theme-context.rst rename to docs/design/theme-context.rst From b051758fb85fb91b40bc4d9a9502bb9a0e726fda Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Thu, 22 Mar 2018 13:58:52 -0500 Subject: [PATCH 15/17] Cleanup extra spaces --- docs/vcs.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/vcs.rst b/docs/vcs.rst index 8ee07b4d101..479e3f02860 100644 --- a/docs/vcs.rst +++ b/docs/vcs.rst @@ -12,7 +12,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 +34,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 +49,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 +72,7 @@ It can be used like this:: {% if display_gitlab %} + {{ conf_py_path }}{{ pagename }}{{ suffix }}" class="fa fa-gitlab"> Edit on GitLab {% endif %} From 55a83b6e3dee89c202828d4fb5380d130113dc91 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Thu, 22 Mar 2018 14:01:23 -0500 Subject: [PATCH 16/17] Add note about the new design for the theme context --- docs/vcs.rst | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/vcs.rst b/docs/vcs.rst index 479e3f02860..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`_. From 4f911f4394c14da6b6a13c638dab56cdb0fcf34c Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Thu, 22 Mar 2018 14:03:06 -0500 Subject: [PATCH 17/17] Update the index --- docs/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index d80a5485cdb..d6e30f31272 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -76,7 +76,7 @@ Information about development is also available: badges alternate_domains localization - theme-context + vcs subprojects conda canonical