Instructions how to setup tools and build documentation locally

diff --git a/docs/contribute/documenting-code.rst b/docs/contribute/documenting-code.rst
index 459f9c5bcd2ef795df159598b569ec876ca450b6..b005e3b610b3e3c19dd39b80f28d7f23f5804347 100644 (file)
--- a/docs/contribute/documenting-code.rst
+++ b/docs/contribute/documenting-code.rst
@@ -171,13 +171,67 @@ OK, but I am new to Sphinx!
 
 3. You will likely want to see how documentation builds and looks like before posting it on the GitHub. There are two options to do so:
 
-    * Install `Sphinx <http://www.sphinx-doc.org/>`_, `Breathe <https://breathe.readthedocs.io/>`_ and `Doxygen <http://www.stack.nl/~dimitri/doxygen/>`_ to build it locally. You would need a Linux machine for that.
+    * Install `Sphinx <http://www.sphinx-doc.org/>`_, `Breathe <https://breathe.readthedocs.io/>`_ and `Doxygen <http://www.stack.nl/~dimitri/doxygen/>`_ to build it locally, see chapter below.
    
     * Set up an account on `Read the Docs <https://readthedocs.org/>`_ and build documentation in the cloud. Read the Docs provides document building and hosting for free and their service works really quick and great.
 
 4. To preview documentation before building use `Sublime Text <https://www.sublimetext.com/>`_ editor together with `OmniMarkupPreviewer <https://github.com/timonwong/OmniMarkupPreviewer>`_ plugin. 
 
 
+Setup for building documentation locally
+----------------------------------------
+
+You can setup environment to build documentation locally on your PC by installing:
+
+1. Doxygen - http://www.stack.nl/~dimitri/doxygen/
+2. Sphinx - https://github.com/sphinx-doc/sphinx/#readme-for-sphinx
+3. Docment theme "sphinx_rtd_theme" - https://github.com/rtfd/sphinx_rtd_theme
+4. Breathe - https://github.com/michaeljones/breathe#breathe
+
+The package "sphinx_rtd_theme" is added to have the same "look and feel" of `ESP32 Programming Guide <http://esp-idf.readthedocs.io/en/latest/index.html>`_ documentation like on the "Read the Docs" hosting site.
+
+Installation of Doxygen is OS dependent:
+
+**Linux**
+
+::
+
+       sudo apt-get install doxygen
+
+**Windows** - install in MSYS2 console
+
+::
+
+       pacman -S doxygen
+
+**MacOS**
+
+::
+
+       brew install doxygen
+
+All remaining applications are `Python <https://www.python.org/>`_ packages and you can install them in one step as follows:
+
+::
+
+       cd ~/esp/esp-idf/docs
+       pip install -r requirements.txt
+
+.. note::
+
+       Installation steps assume that ESP-IDF is placed in ``~/esp/esp-idf`` directory, that is default location of ESP-IDF used in documentation.
+
+Now you should be ready to build documentation by invoking::
+
+       make html
+
+This may take couple of minutes. After completion, documentation will be placed in ``~/esp/esp-idf/docs/_buld/html`` folder. To see it, open ``index.html`` in a web browser.  
+
+.. note::
+
+       If documentation build fails with ``AttributeError: 'NoneType' object has no attribute 'replace'`` message, then apply a fix defined in https://github.com/sphinx-doc/sphinx/issues/3709#issuecomment-299645822 to file ``sphinxrenderer.py``.
+
+
 Wrap up
 -------
 

diff --git a/docs/requirements.txt b/docs/requirements.txt
index 7c17f0c8d019c815c172c382ef43ebfdecf41aaf..3556025994c784e75ce2d5a5e84a04a46c4c33d1 100644 (file)
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,5 +1,5 @@
 # This is a list of python packages used to generate documentation. This file is used with pip:
-# pip install requirements.txt
+# pip install -r requirements.txt
 #
 sphinx==1.5.6
 sphinx-rtd-theme