From 0b5984d1a776dcc0ddf165bf9ea36c4db946d35c Mon Sep 17 00:00:00 2001
From: Adam Paquette <nfs120@gmail.com>
Date: Thu, 23 Feb 2017 01:13:29 -0500
Subject: [PATCH] Improve docs for VCS Integrations (#2592)

Details for how to integrate with GitHub, Bitbucket or Gitlab.
---
 docs/vcs.rst | 87 ++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 64 insertions(+), 23 deletions(-)

diff --git a/docs/vcs.rst b/docs/vcs.rst
index 01ce9ecf8..8ee07b4d1 100644
--- a/docs/vcs.rst
+++ b/docs/vcs.rst
@@ -1,41 +1,82 @@
-VCS Integration
-===============
+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 editing into your own theme, the following variables are available in your custom templates:
+If you want to integrate GitHub, you can put the following snippet into 
+your ``conf.py``::
 
-* github_user - GitHub username
-* github_repo - GitHub repo name
-* github_version - GitHub blob
-* conf_py_path - Path in the checkout to the docs root
-* pagename - Sphinx variable representing the name of the page you're on.
-* display_github
+    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 %}
-        <li><a href="https://github.com/{{ github_user }}/{{ github_repo }}/blob/{{ github_version }}{{ conf_py_path }}{{ pagename }}.rst">
-          Show on GitHub</a></li>
-      {% endif %}
+    {% if display_github %}
+        <li><a href="https://github.com/{{ github_user }}/{{ github_repo }}
+        /blob/{{ github_version }}{{ conf_py_path }}{{ pagename }}.rst">
+        Show on GitHub</a></li>
+    {% endif %}
 
 Bitbucket
 ---------
 
-If you want to integrate Bitbucket editing into your own theme, the following variables are available in your custom templates:
+If you want to integrate Bitbucket, you can put the following snippet into 
+your ``conf.py``::
 
-* bitbucket_user - Bitbucket username
-* bitbucket_repo - Bitbucket repo name
-* bitbucket_version - BitBucket version
-* conf_py_path - Path in the checkout to the docs root
-* pagename - Sphinx variable representing the name of the page you're on.
-* display_bitbucket
+    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 %}
-        <a href="https://bitbucket.org/{{ bitbucket_user }}/{{ bitbucket_repo }}/src/{{ bitbucket_version}}{{ conf_py_path }}{{ pagename }}.rst'" class="icon icon-bitbucket"> Edit on Bitbucket</a>
-      {% endif %}
+    {% if display_bitbucket %}
+        <a href="https://bitbucket.org/{{ bitbucket_user }}/{{ bitbucket_repo }}
+        /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 
+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 %}
+        <a href="https://{{ gitlab_host|default("gitlab.com") }}/
+        {{ gitlab_user }}/{{ gitlab_repo }}/blob/{{ gitlab_version }}
+        {{ conf_py_path }}{{ pagename }}{{ suffix }}" class="fa fa-gitlab"> 
+        Edit on GitLab</a>
+    {% endif %}
+
+Additional variables
+--------------------
+
+* ``'pagename'`` - Sphinx variable representing the name of the page you're on.