From 7c491d23355d79f8fe3dedb1e3d420ffb7c3307e Mon Sep 17 00:00:00 2001
From: Kirill Chalov <kirill.chalov@espressif.com>
Date: Wed, 11 Sep 2019 17:15:00 +0800
Subject: [PATCH 1/2] Allow the extension  for adding todo notes to rst files.
 Add information on how to use this extension to the contribution section.

---
 docs/conf_common.py                     |  6 +++++
 docs/en/contribute/documenting-code.rst | 29 +++++++++++++++++++++++++
 2 files changed, 35 insertions(+)

diff --git a/docs/conf_common.py b/docs/conf_common.py
index 505dab8a0..12616080c 100644
--- a/docs/conf_common.py
+++ b/docs/conf_common.py
@@ -154,8 +154,14 @@ extensions = ['breathe',
               'sphinxcontrib.rackdiag',
               'sphinxcontrib.packetdiag',
               'html_redirects',
+              'sphinx.ext.todo',
               ]
 
+# sphinx.ext.todo extension parameters
+# If the below parameter is True, the extension
+# produces output, else it produces nothing.
+todo_include_todos = False
+
 # Enabling this fixes cropping of blockdiag edge labels
 seqdiag_antialias = True
 
diff --git a/docs/en/contribute/documenting-code.rst b/docs/en/contribute/documenting-code.rst
index fb83f73e1..a75601e26 100644
--- a/docs/en/contribute/documenting-code.rst
+++ b/docs/en/contribute/documenting-code.rst
@@ -215,6 +215,35 @@ Try them out by modifying the source code and see the diagram instantly renderin
     There may be slight differences in rendering of font used by the `interactive shell`_ compared to the font used in the esp-idf documentation.
 
 
+Add Notes
+---------
+
+Working on a document, you might need to:
+
+- Place some suggestions on what should be added or modified in future.
+- Leave a reminder for yourself or somebody else to follow up.
+
+In this case, add a todo note to your reST file using the directive ``.. todo::``. For example:
+
+.. code-block:: none
+
+   .. todo::
+
+      Add a package diagram.
+
+If you add ``.. todolist::`` to a reST file, the directive will be replaced by a list of all todo notes from the whole documentation.
+
+By default, the directives ``.. todo::`` and ``.. todolist::`` are ignored by documentation builders. If you want the notes and the list of notes to be visible in your locally built documentation, do the following:
+
+1. Open your local ``conf_common.py`` file.
+2. Find the parameter ``todo_include_todos``.
+3. Change its value from ``False`` to ``True``.
+
+Before pushing your changes to origin, please set the value of ``todo_include_todos`` back to ``False``.
+
+For more details about the extension, see `its website <https://www.sphinx-doc.org/en/master/usage/extensions/todo.html#directive-todolist>`_.
+
+
 Put it all together
 -------------------
 

From f0dc5f8dc2cc663add1e671f9041cbc08477f522 Mon Sep 17 00:00:00 2001
From: Kirill Chalov <kirill.chalov@espressif.com>
Date: Thu, 12 Sep 2019 12:36:13 +0800
Subject: [PATCH 2/2] Apply suggestion to
 docs/en/contribute/documenting-code.rst

---
 docs/en/contribute/documenting-code.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/en/contribute/documenting-code.rst b/docs/en/contribute/documenting-code.rst
index a75601e26..2a92d8809 100644
--- a/docs/en/contribute/documenting-code.rst
+++ b/docs/en/contribute/documenting-code.rst
@@ -241,7 +241,7 @@ By default, the directives ``.. todo::`` and ``.. todolist::`` are ignored by do
 
 Before pushing your changes to origin, please set the value of ``todo_include_todos`` back to ``False``.
 
-For more details about the extension, see `its website <https://www.sphinx-doc.org/en/master/usage/extensions/todo.html#directive-todolist>`_.
+For more details about the extension, see `sphinx.ext.todo <https://www.sphinx-doc.org/en/master/usage/extensions/todo.html#directive-todolist>`_ documenation.
 
 
 Put it all together