Upgrade `gitlab-markup` to 1.7.0

The new version requires `python3` to be available. In omnibus
installation this is already a reality as we are currently pathing
previous `gitlab-markup` version to use `python3` instead of `python2`.

We are now requiring `python3` with the gem without having to patch it.

As a consequence to also make it easy to use it in development, we've
introduced a `Pipfile` and `Pipfile.lock`, working similarly to
`Gemfile` and `Gemfile.lock`, and added documentation on how to use
them.

7 files changed, 130 insertions, 3 deletions

diff --git a/Gemfile b/Gemfile
index 222503ee6f5..c0815c4a2a6 100644
--- a/Gemfile
+++ b/Gemfile
@@ -116,7 +116,7 @@ gem 'seed-fu', '~> 2.3.7'
 # Markdown and HTML processing
 gem 'html-pipeline', '~> 2.8'
 gem 'deckar01-task_list', '2.2.0'
-gem 'gitlab-markup', '~> 1.6.5'
+gem 'gitlab-markup', '~> 1.7.0'
 gem 'github-markup', '~> 1.7.0', require: 'github/markup'
 gem 'commonmarker', '~> 0.17'
 gem 'RedCloth', '~> 4.3.2'
diff --git a/Gemfile.lock b/Gemfile.lock
index 4c88afc7e24..a8f1f4c8e76 100644
--- a/Gemfile.lock
+++ b/Gemfile.lock
@@ -286,7 +286,7 @@ GEM
     github-markup (1.7.0)
     gitlab-default_value_for (3.1.1)
       activerecord (>= 3.2.0, < 6.0)
-    gitlab-markup (1.6.5)
+    gitlab-markup (1.7.0)
     gitlab-sidekiq-fetcher (0.4.0)
       sidekiq (~> 5)
     gitlab-styles (2.5.1)
@@ -1020,7 +1020,7 @@ DEPENDENCIES
   gitaly-proto (~> 1.13.0)
   github-markup (~> 1.7.0)
   gitlab-default_value_for (~> 3.1.1)
-  gitlab-markup (~> 1.6.5)
+  gitlab-markup (~> 1.7.0)
   gitlab-sidekiq-fetcher (~> 0.4.0)
   gitlab-styles (~> 2.4)
   gitlab_omniauth-ldap (~> 2.1.1)
diff --git a/Pipfile b/Pipfile
new file mode 100644
index 00000000000..2afbe5fc3f2
--- /dev/null
+++ b/Pipfile
@@ -0,0 +1,12 @@
+[[source]]
+name = "pypi"
+url = "https://pypi.org/simple"
+verify_ssl = true
+
+[dev-packages]
+
+[packages]
+docutils = "==0.13.1"
+
+[requires]
+python_version = "3.4"
diff --git a/Pipfile.lock b/Pipfile.lock
new file mode 100644
index 00000000000..dc23ca89ed2
--- /dev/null
+++ b/Pipfile.lock
@@ -0,0 +1,30 @@
+{
+    "_meta": {
+        "hash": {
+            "sha256": "ec82d5e7c10fd591aeebbc9b7b62d730f7fd70dc52e4e4818834891aa4194c73"
+        },
+        "pipfile-spec": 6,
+        "requires": {
+            "python_version": "3.4"
+        },
+        "sources": [
+            {
+                "name": "pypi",
+                "url": "https://pypi.org/simple",
+                "verify_ssl": true
+            }
+        ]
+    },
+    "default": {
+        "docutils": {
+            "hashes": [
+                "sha256:718c0f5fb677be0f34b781e04241c4067cbd9327b66bdd8e763201130f5175be",
+                "sha256:cb3ebcb09242804f84bdbf0b26504077a054da6772c6f4d625f335cc53ebf94d",
+                "sha256:de454f1015958450b72641165c08afe7023cd7e3944396448f2fb1b0ccba9d77"
+            ],
+            "index": "pypi",
+            "version": "==0.13.1"
+        }
+    },
+    "develop": {}
+}
diff --git a/changelogs/unreleased/59062-update-gitlab-markup-python-3.yml b/changelogs/unreleased/59062-update-gitlab-markup-python-3.yml
new file mode 100644
index 00000000000..265a7e36841
--- /dev/null
+++ b/changelogs/unreleased/59062-update-gitlab-markup-python-3.yml
@@ -0,0 +1,5 @@
+---
+title: Update gitlab-markup to 1.7.0 which requies python3
+merge_request: 26246
+author:
+type: changed
diff --git a/doc/development/contributing/style_guides.md b/doc/development/contributing/style_guides.md
index 0eedef5e14f..45104a1f91d 100644
--- a/doc/development/contributing/style_guides.md
+++ b/doc/development/contributing/style_guides.md
@@ -22,6 +22,7 @@
    text should be _sorry, we could not create your account because:_
 1. Code should be written in [US English][us-english]
 1. [Go](../go_guide/index.md)
+1. [Python](../python_guide/index.md)
 
 This is also the style used by linting tools such as
 [RuboCop](https://github.com/bbatsov/rubocop) and [Hound CI](https://houndci.com).
diff --git a/doc/development/python_guide/index.md b/doc/development/python_guide/index.md
new file mode 100644
index 00000000000..6025dc9ebf2
--- /dev/null
+++ b/doc/development/python_guide/index.md
@@ -0,0 +1,79 @@
+# Python Development Guidelines
+
+GitLab requires Python as a dependency for [reStructuredText](http://docutils.sourceforge.net/rst.html)
+markup rendering.
+
+As of GitLab 11.10, we require Python 3.
+
+## Installation
+
+There are several ways of installing python on your system. To be able to use the same version we use in production,
+we suggest you use [pyenv](https://github.com/pyenv/pyenv). It works and behave similar to its counterpart in the
+ruby world: [rbenv](https://github.com/rbenv/rbenv).
+
+### macOS
+
+To install `pyenv` on macOS, you can use [Homebrew](https://brew.sh/) with:
+
+```bash
+brew install pyenv
+```
+
+### Linux
+
+To install `pyenv` on Linux, you can run the command below:
+
+```bash
+curl https://pyenv.run | bash
+```
+
+Alternatively, you may find `pypenv` available as a system package via your distro package manager.
+
+You can read more about it in: <https://github.com/pyenv/pyenv-installer#prerequisites>.
+
+### Shell integration
+
+Pyenv installation will add required changes to Bash. If you use a different shell,
+check for any additional steps required for it.
+
+For Fish, you can install a plugin for [Fisherman](https://github.com/fisherman/fisherman):
+
+```bash
+fisher add fisherman/pyenv
+```
+
+Or for [Oh My Fish](https://github.com/oh-my-fish/oh-my-fish):
+
+```bash
+omf install pyenv
+```
+
+## Dependency management
+
+While GitLab doesn't directly contain any Python scripts, because we depend on Python to render
+[reStructuredText](http://docutils.sourceforge.net/rst.html) markup, we need to keep track on dependencies
+on the main project level, so we can run that on our development machines.
+
+Recently, an equivalent to the `Gemfile` and the [Bundler](https://bundler.io/) project has been introduced to Python:
+`Pipfile` and [Pipenv](https://pipenv.readthedocs.io/en/latest/).
+
+You will now find a `Pipfile` with the dependencies in the root folder. To install them, run:
+
+```bash
+pipenv install
+```
+
+Running this command will install both the required Python version as well as required pip dependencies.
+
+## Use instructions
+
+To run any python code under the Pipenv environment, you need to first start a `virtualenv` based on the dependencies
+of the application. With Pipenv, this is a simple as running:
+
+```bash
+pipenv shell
+```
+
+After running that command, you can run GitLab on the same shell and it will be using the Python and dependencies
+installed from the `pipenv install` command.
+