Merge branch 'feature/docs_setup_sphinx' into 'master'

Instructions how to setup tools and  build documentation locally

See merge request !1063

docs/Doxyfile

@@ -25,7 +25,7 @@ INPUT = \
     ## Wi-Fi - API Reference
     ##
     ../components/esp32/include/esp_wifi.h \
-    ../components/esp32/include/esp_wifi_crypto_types.h\
+    ../components/esp32/include/esp_wifi_crypto_types.h \
     ../components/esp32/include/esp_smartconfig.h \
     ## Bluetooth - API Reference
     ## Controller && VHCI

docs/api-guides/wifi.rst

@@ -1220,7 +1220,7 @@ ESP32 Wi-Fi Connect Crypto
 -----------------------------------
 Now ESP32 have two group crypto functions can be used when do wifi connect, one is the original functions, the other is optimized by ESP hardware:
 1. Original functions which is the source code used in the folder components/wpa_supplicant/src/crypto function;
-2. The optimized functions is in the folder components/wpa_supplicant/src/fast_crypto, these function used the hardware crypto to make it faster than origin one, the type of function's name add fast_ to distinguish with the original one. For example, the API aes_wrap() is used to encrypt frame information when do 4 way handshake, the fast_aes_wrap() has the same result but can be faster.
+2. The optimized functions is in the folder components/wpa_supplicant/src/fast_crypto, these function used the hardware crypto to make it faster than origin one, the type of function's name add `fast_` to distinguish with the original one. For example, the API aes_wrap() is used to encrypt frame information when do 4 way handshake, the fast_aes_wrap() has the same result but can be faster.
 
 Two groups of crypto function can be used when register in the wpa_crypto_funcs_t, wpa2_crypto_funcs_t and wps_crypto_funcs_t structure, also we have given the recommend functions to register in the 
 fast_crypto_ops.c, you can register the function as the way you need, however what should make action is that the crypto_hash_xxx function and crypto_cipher_xxx function need to register with the same function to operation. For example, if you register crypto_hash_init() function to initialize the esp_crypto_hash structure, you need use the crypto_hash_update() and crypto_hash_finish() function to finish the operation, rather than fast_crypto_hash_update() or fast_crypto_hash_finish(). 

docs/contribute/documenting-code.rst

@@ -171,13 +171,63 @@ 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.  
+
+
 Wrap up
 -------
 

docs/requirements.txt

@@ -1,6 +1,6 @@
 # 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
-breathe
+breathe==4.6.0