From bd47f405a36e43429ef9266ae81853d04dcdb0f7 Mon Sep 17 00:00:00 2001
From: Anuj Deshpande <anuj@espressif.com>
Date: Thu, 11 Jan 2018 14:52:54 +0800
Subject: [PATCH] docs : Add support for markdown files

---
 docs/conf.py                         | 8 ++++++--
 docs/contribute/documenting-code.rst | 3 ++-
 docs/requirements.txt                | 3 ++-
 3 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index caa233c93..aee4803d4 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -70,7 +70,11 @@ breathe_default_project = "esp32-idf"
 templates_path = ['_templates']
 
 # The suffix of source filenames.
-source_suffix = '.rst'
+source_suffix = ['.rst', '.md']
+
+source_parsers = {
+       '.md': 'recommonmark.parser.CommonMarkParser',
+    }
 
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'
@@ -111,7 +115,7 @@ print 'Version: {0}  Release: {1}'.format(version, release)
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['_build']
+exclude_patterns = ['_build','README.md']
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
diff --git a/docs/contribute/documenting-code.rst b/docs/contribute/documenting-code.rst
index 228ff74b5..fa73f6032 100644
--- a/docs/contribute/documenting-code.rst
+++ b/docs/contribute/documenting-code.rst
@@ -198,7 +198,7 @@ Once documentation is ready, follow instruction in :doc:`../api-reference/templa
 OK, but I am new to Sphinx!
 ---------------------------
 
-1. No worries. All the software you need is well documented. It is also open source and free. Start by checking `Sphinx <http://www.sphinx-doc.org/>`_ documentation. If you are not clear how to write using rst markup language, see `reStructuredText Primer <http://www.sphinx-doc.org/en/stable/rest.html>`_.
+1. No worries. All the software you need is well documented. It is also open source and free. Start by checking `Sphinx <http://www.sphinx-doc.org/>`_ documentation. If you are not clear how to write using rst markup language, see `reStructuredText Primer <http://www.sphinx-doc.org/en/stable/rest.html>`_. You can also use markdown (.md) files, and find out about more about the specific markdown syntax that we use on`Recommonmark parser's documentation page <https://recommonmark.readthedocs.io/en/latest/>`_.
 
 2. Check the source files of this documentation to understand what is behind of what you see now on the screen. Sources are maintained on GitHub in `espressif/esp-idf`_ repository in :idf:`docs` folder. You can go directly to the source file of this page by scrolling up and clicking the link in the top right corner. When on GitHub, see what's really inside, open source files by clicking ``Raw`` button.
 
@@ -221,6 +221,7 @@ You can setup environment to build documentation locally on your PC by installin
 3. Docment theme "sphinx_rtd_theme" - https://github.com/rtfd/sphinx_rtd_theme
 4. Breathe - https://github.com/michaeljones/breathe#breathe
 5. Blockdiag - http://blockdiag.com/en/index.html
+6. Recommonmark - https://github.com/rtfd/recommonmark
 
 The package "sphinx_rtd_theme" is added to have the same "look and feel" of `ESP32 Programming Guide <https://esp-idf.readthedocs.io/en/latest/index.html>`_ documentation like on the "Read the Docs" hosting site.
 
diff --git a/docs/requirements.txt b/docs/requirements.txt
index 8aaf322a9..b85fc09a1 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -7,4 +7,5 @@ breathe==4.7.3
 sphinxcontrib.blockdiag==1.5.3
 sphinxcontrib.seqdiag==0.8.5
 sphinxcontrib.actdiag==0.8.5
-sphinxcontrib.nwdiag==0.9.5
\ No newline at end of file
+sphinxcontrib.nwdiag==0.9.5
+recommonmark