Merge branch 'feature/docs_setup_sphinx' into 'master'
Instructions how to setup tools and build documentation locally See merge request !1063
This commit is contained in:
commit
6c892e3cca
4 changed files with 55 additions and 5 deletions
|
@ -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
|
||||
|
|
|
@ -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().
|
||||
|
|
|
@ -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
|
||||
-------
|
||||
|
||||
|
|
|
@ -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
|
||||
|
|
Loading…
Reference in a new issue