From 01dfe96f977c527f3fe42034bc60d657d8d9f582 Mon Sep 17 00:00:00 2001
From: Sviatoslav Sydorenko <wk@sydorenko.org.ua>
Date: Mon, 22 Nov 2021 02:18:57 +0100
Subject: [PATCH] Include contributing guidelines in Sphinx docs

---
 docs/conf.py                    |  1 +
 docs/contributing/guidelines.md | 34 +++++++++++++++++++++++++++++++++
 docs/index.md                   |  1 +
 3 files changed, 36 insertions(+)
 create mode 100644 docs/contributing/guidelines.md

diff --git a/docs/conf.py b/docs/conf.py
index ec96d7c5dd..20e36ac5ca 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -159,6 +159,7 @@
 # -- Options for intersphinx extension ---------------------------------------
 
 intersphinx_mapping = {
+    'myst': ('https://myst-parser.rtfd.io/en/latest', None),
     'python': ('https://docs.python.org/3', None),
     'python2': ('https://docs.python.org/2', None),
 }
diff --git a/docs/contributing/guidelines.md b/docs/contributing/guidelines.md
new file mode 100644
index 0000000000..c12c38338c
--- /dev/null
+++ b/docs/contributing/guidelines.md
@@ -0,0 +1,34 @@
+```{spelling}
+de
+facto
+Pre
+reStructuredText
+```
+
+```{include} ../../CONTRIBUTING.md
+```
+
+# Contributing docs
+
+We use [Sphinx] to generate our docs website. You can trigger
+the process locally by executing:
+
+```shell-session
+$ tox -e build-docs
+```
+
+It is also integrated with [Read The Docs] that builds and
+publishes each commit to the main branch and generates live
+docs previews for each pull request.
+
+The sources of the [Sphinx] documents use reStructuredText as a
+de-facto standard. But in order to make contributing docs more
+beginner-friendly, we have integrated [MyST parser] allowing us
+to also accept new documents written in an extended version of
+Markdown that supports using Sphinx directives and roles. {ref}`Read
+the docs <myst:intro/writing>` to learn more on how to use it.
+
+
+[MyST parser]: https://pypi.org/project/myst-parser/
+[Read The Docs]: https://readthedocs.org
+[Sphinx]: https://www.sphinx-doc.org
diff --git a/docs/index.md b/docs/index.md
index 9c461a1543..aefb3dc7c6 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -36,6 +36,7 @@ Glossary <glossary>
 :hidden:
 
 Code Of Conduct <contributing/code_of_conduct>
+contributing/guidelines
 contributing/security
 Private unsupported (dev) API autodoc <pkg/modules>
 ```