From: krzychb <krzychb@gazeta.pl>
Date: Sat, 29 Jul 2017 13:25:00 +0000 (+0200)
Subject: Instructions how to setup tools and  build documentation locally
X-Git-Tag: v3.1-dev~415^2~2
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=2e94b51b9c790e369211fd80bf292d36d6033638;p=esp-idf

Instructions how to setup tools and  build documentation locally
---

diff --git a/docs/contribute/documenting-code.rst b/docs/contribute/documenting-code.rst
index 459f9c5bcd..b005e3b610 100644
--- 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 7c17f0c8d0..3556025994 100644
--- 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