diff --git a/.gitignore b/.gitignore index f11370493d..82f7fd3f2b 100644 --- a/.gitignore +++ b/.gitignore @@ -27,6 +27,7 @@ examples/*/*/build docs/_build/ docs/doxygen-warning-log.txt docs/xml/ +docs/man/ # Unit test app files tools/unit-test-app/sdkconfig diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 81a8fba4fb..6cbac58741 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -125,6 +125,7 @@ build_docs: - doxygen # If not building master branch, and there are Doxygen warnings, print them and bail out - test "${CI_BUILD_REF_NAME}" = "master" || test $(cat doxygen-warning-log.txt | wc -l) -eq 0 || ( echo "Doxygen pass had some warnings:" && cat doxygen-warning-log.txt && false ) + - make gh-linkcheck - make html artifacts: paths: @@ -246,6 +247,26 @@ deploy_docs: - scp $GIT_VER.tar.gz $DOCS_SERVER:$DOCS_PATH - ssh $DOCS_SERVER -x "cd $DOCS_PATH && tar xzvf $GIT_VER.tar.gz && rm -f latest && ln -s $GIT_VER latest" +check_doc_links: + stage: test + image: espressif/esp32-ci-env + tags: + - check_doc_links + only: + # can only be triggered + - triggers + script: + # must be triggered with CHECK_LINKS=Yes, otherwise exit without test + - test $CHECK_LINKS = "Yes" || exit 0 + # can only run on master branch (otherwise the commit is not on Github yet) + - test "${CI_BUILD_REF_NAME}" = "master" || exit 0 + - cd docs + - make linkcheck + artifacts: + paths: + - docs/_build/linkcheck + expire_in: 1 mos + # AUTO GENERATED PART START, DO NOT MODIFY CONTENT BELOW # template for test jobs diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 5810d06b98..df40705044 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -21,7 +21,7 @@ Before sending us a Pull Request, please consider this list of points: * Is the code adequately commented for people to understand how it is structured? -* Is there documentation or examples that go with code contributions? `There are additional suggestions for writing good examples in the examples README `_. +* Is there documentation or examples that go with code contributions? There are additional suggestions for writing good examples in :idf:`examples` readme. * Are comments and documentation written in clear English, with no spelling or grammar errors? diff --git a/components/vfs/README.rst b/components/vfs/README.rst index 2ad7aa7ec2..26d857fc8d 100644 --- a/components/vfs/README.rst +++ b/components/vfs/README.rst @@ -140,7 +140,7 @@ actually is translated to to this (by the preprocessor): fprintf(__getreent()->_stderr, "42\n"); -where the ``__getreent()`` function returns a per-task pointer to ``struct _reent`` (`source `_). This structure is allocated on the TCB of each task. When a task is initialized, ``_stdin``, ``_stdout`` and ``_stderr`` members of ``struct _reent`` are set to the values of ``_stdin``, ``_stdout`` and ``_stderr`` of ``_GLOBAL_REENT`` (i.e. the structure which is used before FreeRTOS is started). +where the ``__getreent()`` function returns a per-task pointer to ``struct _reent`` (:component_file:`newlib/include/sys/reent.h#L370-L417>`). This structure is allocated on the TCB of each task. When a task is initialized, ``_stdin``, ``_stdout`` and ``_stderr`` members of ``struct _reent`` are set to the values of ``_stdin``, ``_stdout`` and ``_stderr`` of ``_GLOBAL_REENT`` (i.e. the structure which is used before FreeRTOS is started). Such a design has the following consequences: diff --git a/docs/COPYRIGHT.rst b/docs/COPYRIGHT.rst index 67b3d9bf1c..0e0d457207 100644 --- a/docs/COPYRIGHT.rst +++ b/docs/COPYRIGHT.rst @@ -14,7 +14,7 @@ Additional third party copyrighted code is included under the following licenses * Xtensa header files (components/esp32/include/xtensa) are Copyright (C) 2013 Tensilica Inc and are licensed under the MIT License as reproduce in the individual header files. -* `esptool.py`_ (bin/esptool.py) is Copyright (C) 2014-2016 Fredrik Ahlberg, Angus Gratton and is licensed under the GNU General Public License v2, as described in the file components/esptool_py/LICENSE. +* `esptool.py`_ (components/esptool_py/esptool) is Copyright (C) 2014-2016 Fredrik Ahlberg, Angus Gratton and is licensed under the GNU General Public License v2, as described in the file components/esptool_py/LICENSE. * Original parts of FreeRTOS_ (components/freertos) are Copyright (C) 2015 Real Time Engineers Ltd and is licensed under the GNU General Public License V2 with the FreeRTOS Linking Exception, as described in the file components/freertos/license.txt. @@ -96,7 +96,7 @@ Copyright (C) 2011, ChaN, all right reserved. .. _Newlib: https://sourceware.org/newlib/ .. _FreeRTOS: http://freertos.org/ -.. _esptool.py: https://github.com/themadinventor/esptool +.. _esptool.py: https://github.com/espressif/esptool .. _LWIP: http://savannah.nongnu.org/projects/lwip/ .. _TinyBasic: https://github.com/BleuLlama/TinyBasicPlus .. _miniz: https://code.google.com/archive/p/miniz/ diff --git a/docs/Makefile b/docs/Makefile index c04268ff1d..8076416b78 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -161,6 +161,30 @@ linkcheck: @echo "Link check complete; look for any errors in the above output " \ "or in $(BUILDDIR)/linkcheck/output.txt." +gh-linkcheck: + @echo "Checking for hardcoded GitHub links" + @if (find ../ -name '*.rst' | xargs grep \ + 'https://github.com/espressif/esp-idf/tree\|https://github.com/espressif/esp-idf/blob\|https://github.com/espressif/esp-idf/raw'\ + ); \ + then \ + echo "WARNINIG: Some .rst files contain hardcoded Github links."; \ + echo "Please check above output and replace links with one of the following:"; \ + echo "- :idf:\`dir\` - points to directory inside ESP-IDF"; \ + echo "- :idf_blob:\`file\` - points to file inside ESP-IDF"; \ + echo "- :idf_raw:\`file\` - points to raw view of the file inside ESP-IDF"; \ + echo "- :component:\`dir\` - points to directory inside ESP-IDF components dir"; \ + echo "- :component_blob:\`file\` - points to file inside ESP-IDF components dir"; \ + echo "- :component_raw:\`file\` - points to raw view of the file inside ESP-IDF"; \ + echo " components dir"; \ + echo "- :example:\`dir\` - points to directory inside ESP-IDF examples dir"; \ + echo "- :example_blob:\`file\` - points to file inside ESP-IDF examples dir"; \ + echo "- :example_raw:\`file\` - points to raw view of the file inside ESP-IDF"; \ + echo " examples dir"; \ + echo "These link types will point to the correct GitHub version automatically"; \ + exit 1; \ + fi + @echo "No hardcoded links found" + doctest: $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest @echo "Testing of doctests in the sources finished, look at the " \ diff --git a/docs/api/bluetooth/controller_vhci.rst b/docs/api/bluetooth/controller_vhci.rst index dfad1af25e..35248cbb1e 100644 --- a/docs/api/bluetooth/controller_vhci.rst +++ b/docs/api/bluetooth/controller_vhci.rst @@ -11,9 +11,9 @@ Overview Application Example ------------------- -Check `/examples/bluetooth `_ folder of `espressif/esp-idf `_ repository, that contains the following example: +Check :example:`bluetooth` folder in ESP-IDF examples, which contains the following example: -`ble_adv `_ +:example:`bluetooth/ble_adv` This is a BLE advertising demo with virtual HCI interface. Send Reset/ADV_PARAM/ADV_DATA/ADV_ENABLE HCI command for BLE advertising. @@ -23,7 +23,7 @@ API Reference Header Files ^^^^^^^^^^^^ - * `bt/include/bt.h `_ + * :component_file:`bt/include/bt.h` Type Definitions ^^^^^^^^^^^^^^^^ diff --git a/docs/api/bluetooth/esp_blufi.rst b/docs/api/bluetooth/esp_blufi.rst index 442e54f5ca..5a1b1595a9 100644 --- a/docs/api/bluetooth/esp_blufi.rst +++ b/docs/api/bluetooth/esp_blufi.rst @@ -11,9 +11,9 @@ Use should concern these things: Application Example ------------------- -Check `/examples/bluetooth `_ folder of `espressif/esp-idf `_ repository, that contains the following example: +Check :example:`bluetooth` folder in ESP-IDF examples, which contains the following example: -`blufi `_ +:example:`bluetooth/blufi` This is a BLUFI demo. This demo can set ESP32's wifi to softap/station/softap&station mode and config wifi connections. @@ -24,7 +24,7 @@ API Reference Header Files ^^^^^^^^^^^^ - * `bt/bluedroid/api/include/esp_blufi_api.h `_ + * :component_file:`bt/bluedroid/api/include/esp_blufi_api.h` Macros ^^^^^^ diff --git a/docs/api/bluetooth/esp_bt_defs.rst b/docs/api/bluetooth/esp_bt_defs.rst index 217dfb7620..527fe9359f 100644 --- a/docs/api/bluetooth/esp_bt_defs.rst +++ b/docs/api/bluetooth/esp_bt_defs.rst @@ -20,7 +20,7 @@ API Reference Header Files ^^^^^^^^^^^^ - * `bt/bluedroid/api/include/esp_bt_defs.h `_ + * :component_file:`bt/bluedroid/api/include/esp_bt_defs.h` Macros diff --git a/docs/api/bluetooth/esp_bt_device.rst b/docs/api/bluetooth/esp_bt_device.rst index 79c2e9c9bf..50e9dcf1a0 100644 --- a/docs/api/bluetooth/esp_bt_device.rst +++ b/docs/api/bluetooth/esp_bt_device.rst @@ -22,7 +22,7 @@ API Reference Header Files ^^^^^^^^^^^^ - * `bt/bluedroid/api/include/esp_bt_device.h `_ + * :component_file:`bt/bluedroid/api/include/esp_bt_device.h` Macros diff --git a/docs/api/bluetooth/esp_bt_main.rst b/docs/api/bluetooth/esp_bt_main.rst index f44dc7eebc..1c085a1347 100644 --- a/docs/api/bluetooth/esp_bt_main.rst +++ b/docs/api/bluetooth/esp_bt_main.rst @@ -20,7 +20,7 @@ API Reference Header Files ^^^^^^^^^^^^ - * `bt/bluedroid/api/include/esp_bt_main.h `_ + * :component_file:`bt/bluedroid/api/include/esp_bt_main.h` Macros diff --git a/docs/api/bluetooth/esp_gap_ble.rst b/docs/api/bluetooth/esp_gap_ble.rst index f53b8d56ad..9b2fb1ea07 100644 --- a/docs/api/bluetooth/esp_gap_ble.rst +++ b/docs/api/bluetooth/esp_gap_ble.rst @@ -11,11 +11,11 @@ Overview Application Example ------------------- -Check `/examples/bluetooth `_ folder of `espressif/esp-idf `_ repository, that contains the following examples: +Check :example:`bluetooth` folder in ESP-IDF examples, which contains the following examples: -`gatt_server `_, `gatt_client `_ +:example:`bluetooth/gatt_server`, :example:`bluetooth/gatt_client` - The two demos use different gap api, such like advertising, scan, set device name and others. + The two demos use different GAP APIs, such like advertising, scan, set device name and others. API Reference ------------- @@ -23,7 +23,7 @@ API Reference Header Files ^^^^^^^^^^^^ - * `bt/bluedroid/api/include/esp_gap_ble_api.h `_ + * :component_file:`bt/bluedroid/api/include/esp_gap_ble_api.h` Macros diff --git a/docs/api/bluetooth/esp_gatt_defs.rst b/docs/api/bluetooth/esp_gatt_defs.rst index 621c6d95e1..11cb640279 100644 --- a/docs/api/bluetooth/esp_gatt_defs.rst +++ b/docs/api/bluetooth/esp_gatt_defs.rst @@ -20,7 +20,7 @@ API Reference Header Files ^^^^^^^^^^^^ - * `bt/bluedroid/api/include/esp_gatt_defs.h `_ + * :component_file:`bt/bluedroid/api/include/esp_gatt_defs.h` Macros diff --git a/docs/api/bluetooth/esp_gattc.rst b/docs/api/bluetooth/esp_gattc.rst index adfc225dfa..b41c7e09e3 100644 --- a/docs/api/bluetooth/esp_gattc.rst +++ b/docs/api/bluetooth/esp_gattc.rst @@ -11,11 +11,11 @@ Overview Application Example ------------------- -Check `/examples/bluetooth `_ folder of `espressif/esp-idf `_ repository, that contains the following example: +Check :example:`bluetooth` folder in ESP-IDF examples, which contains the following examples: -`gatt_client `_ +:example:`bluetooth/gatt_client` - This is a gatt client demo. This demo can scan devices, connect to the gatt server and discover the service. + This is a GATT client demo. This demo can scan devices, connect to the GATT server and discover the service. API Reference @@ -24,7 +24,7 @@ API Reference Header Files ^^^^^^^^^^^^ - * `bt/bluedroid/api/include/esp_gattc_api.h `_ + * :component_file:`bt/bluedroid/api/include/esp_gattc_api.h` Macros ^^^^^^ diff --git a/docs/api/bluetooth/esp_gatts.rst b/docs/api/bluetooth/esp_gatts.rst index 4753490d4d..8f0414d67f 100644 --- a/docs/api/bluetooth/esp_gatts.rst +++ b/docs/api/bluetooth/esp_gatts.rst @@ -11,11 +11,11 @@ Overview Application Example ------------------- -Check `/examples/bluetooth `_ folder of `espressif/esp-idf `_ repository, that contains the following example: +Check :example:`bluetooth` folder in ESP-IDF examples, which contains the following example: -`gatt_server `_ +:example:`bluetooth/gatt_server` - This is a gatt server demo. Use gatt api to create a gatt server with send advertising. This gatt server can be connected and the service can be discovery. + This is a GATT server demo. Use GATT API to create a GATT server with send advertising. This GATT server can be connected and the service can be discovery. API Reference ------------- @@ -23,7 +23,7 @@ API Reference Header Files ^^^^^^^^^^^^ - * `bt/bluedroid/api/include/esp_gatts_api.h `_ + * :component_file:`bt/bluedroid/api/include/esp_gatts_api.h` Macros ^^^^^^ diff --git a/docs/api/bluetooth/index.rst b/docs/api/bluetooth/index.rst index 5a096c75ef..996a26e138 100644 --- a/docs/api/bluetooth/index.rst +++ b/docs/api/bluetooth/index.rst @@ -9,4 +9,4 @@ Bluetooth API Bluetooth LE -Example code for this API section is provided in `examples/bluetooth `_ directory of ESP-IDF repository. +Example code for this API section is provided in :example:`bluetooth` directory of ESP-IDF examples. diff --git a/docs/api/ethernet/esp_eth.rst b/docs/api/ethernet/esp_eth.rst index 5702389af8..fbecdca339 100644 --- a/docs/api/ethernet/esp_eth.rst +++ b/docs/api/ethernet/esp_eth.rst @@ -4,7 +4,7 @@ ETHERNET Application Example ------------------- -ethernet example: `examples/ethernet/ethernet `_. +Ethernet example: :example:`ethernet/ethernet`. API Reference ------------- @@ -12,7 +12,7 @@ API Reference Header Files ^^^^^^^^^^^^ - * `components/ethernet/include/esp_eth.h `_ + * :component_file:`ethernet/include/esp_eth.h` Macros ^^^^^^ diff --git a/docs/api/ethernet/index.rst b/docs/api/ethernet/index.rst index 31181d23ea..6e95831d32 100644 --- a/docs/api/ethernet/index.rst +++ b/docs/api/ethernet/index.rst @@ -7,4 +7,4 @@ Ethernet API Ethernet -Example code for this API section is provided in `examples/ethernet `_ directory of ESP-IDF repository. +Example code for this API section is provided in :example:`ethernet` directory of ESP-IDF examples. diff --git a/docs/api/peripherals/gpio.rst b/docs/api/peripherals/gpio.rst index 643eac1f4d..da3f4607ea 100644 --- a/docs/api/peripherals/gpio.rst +++ b/docs/api/peripherals/gpio.rst @@ -10,7 +10,7 @@ Note that GPIO6-11 are usually used for SPI flash. GPIO34-39 can only be set as Application Example ------------------- -GPIO output and input interrupt example: `examples/peripherals/gpio `_. +GPIO output and input interrupt example: :example:`peripherals/gpio`. API Reference ------------- @@ -18,7 +18,7 @@ API Reference Header Files ^^^^^^^^^^^^ - * `driver/include/driver/driver/gpio.h `_ + * :component_file:`driver/include/driver/gpio.h` Macros ^^^^^^ diff --git a/docs/api/peripherals/i2c.rst b/docs/api/peripherals/i2c.rst index 93d863da6b..bd30a345d8 100644 --- a/docs/api/peripherals/i2c.rst +++ b/docs/api/peripherals/i2c.rst @@ -9,7 +9,7 @@ ESP32 has two I2C controllers which can be set as master mode or slave mode. Application Example ------------------- -I2C master and slave example: `examples/peripherals/i2c `_. +I2C master and slave example: :example:`peripherals/i2c`. API Reference ------------- @@ -17,7 +17,7 @@ API Reference Header Files ^^^^^^^^^^^^ - * `driver/include/driver/i2c.h `_ + * :component_file:`driver/include/driver/i2c.h` Macros ^^^^^^ diff --git a/docs/api/peripherals/index.rst b/docs/api/peripherals/index.rst index 147a722fc6..f3c1dbe4a3 100644 --- a/docs/api/peripherals/index.rst +++ b/docs/api/peripherals/index.rst @@ -15,4 +15,4 @@ Peripherals API Remote Control -Example code for this API section is provided in `examples/peripherals `_ directory of ESP-IDF repository. +Example code for this API section is provided in :example:`peripherals` directory of ESP-IDF examples. diff --git a/docs/api/peripherals/ledc.rst b/docs/api/peripherals/ledc.rst index 8c55e2413b..a1a96543dc 100644 --- a/docs/api/peripherals/ledc.rst +++ b/docs/api/peripherals/ledc.rst @@ -12,7 +12,7 @@ decrease the duty cycle gradually, allowing for fades without any processor inte Application Example ------------------- -LEDC change duty cycle and fading control example: `examples/peripherals/ledc `_. +LEDC change duty cycle and fading control example: :example:`peripherals/ledc`. API Reference ------------- @@ -20,7 +20,7 @@ API Reference Header Files ^^^^^^^^^^^^ - * `driver/include/driver/ledc.h `_ + * :component_file:`driver/include/driver/ledc.h` Macros ^^^^^^ diff --git a/docs/api/peripherals/pcnt.rst b/docs/api/peripherals/pcnt.rst index bf4fcd0406..63e6ad6443 100644 --- a/docs/api/peripherals/pcnt.rst +++ b/docs/api/peripherals/pcnt.rst @@ -9,7 +9,7 @@ The PCNT (Pulse Counter) module is designed to count the number of rising and/or Application Example ------------------- -Pulse counter with control signal and event interrupt example: `examples/peripherals/pcnt `_. +Pulse counter with control signal and event interrupt example: :example:`peripherals/pcnt`. API Reference ------------- @@ -17,7 +17,7 @@ API Reference Header Files ^^^^^^^^^^^^ - * `driver/pcnt.h `_ + * :component_file:`driver/include/driver/pcnt.h` Macros diff --git a/docs/api/peripherals/rmt.rst b/docs/api/peripherals/rmt.rst index 715bc46786..276ed939e1 100644 --- a/docs/api/peripherals/rmt.rst +++ b/docs/api/peripherals/rmt.rst @@ -9,7 +9,7 @@ The RMT (Remote Control) module driver can be used to send and receive infrared Application Example ------------------- -NEC remote control TX and RX example: `examples/peripherals/rmt_nec_tx_rx `_. +NEC remote control TX and RX example: :example:`peripherals/rmt_nec_tx_rx`. API Reference ------------- @@ -17,7 +17,7 @@ API Reference Header Files ^^^^^^^^^^^^ - * `driver/rmt.h `_ + * :component_file:`driver/include/driver/rmt.h` Macros ^^^^^^ diff --git a/docs/api/peripherals/sigmadelta.rst b/docs/api/peripherals/sigmadelta.rst index 56e4d77e72..fb51ae8b03 100644 --- a/docs/api/peripherals/sigmadelta.rst +++ b/docs/api/peripherals/sigmadelta.rst @@ -10,7 +10,7 @@ This driver configures the channels of the sigma-delta module. Application Example ------------------- -Sigma-delta Modulation example: `examples/peripherals/sigmadelta `_. +Sigma-delta Modulation example: :example:`peripherals/sigmadelta`. API Reference ------------- @@ -18,7 +18,7 @@ API Reference Header Files ^^^^^^^^^^^^ - * `driver/sigmadelta.h `_ + * :component_file:`driver/include/driver/sigmadelta.h` Macros diff --git a/docs/api/peripherals/spi_master.rst b/docs/api/peripherals/spi_master.rst index 9e5c0eb636..78039cbd79 100644 --- a/docs/api/peripherals/spi_master.rst +++ b/docs/api/peripherals/spi_master.rst @@ -108,7 +108,7 @@ as ``tx_data`` and ``rx_data``. Application Example ------------------- -Display graphics on the ILI9341-based 320x240 LCD: `examples/peripherals/spi_master `_. +Display graphics on the ILI9341-based 320x240 LCD: :example:`peripherals/spi_master`. API Reference ------------- @@ -116,7 +116,7 @@ API Reference Header Files ^^^^^^^^^^^^ - * `driver/include/driver/spi_master.h `_ + * :component_file:`driver/include/driver/spi_master.h` Macros ^^^^^^ diff --git a/docs/api/peripherals/timer.rst b/docs/api/peripherals/timer.rst index 203c6b0d30..7b5253fde1 100644 --- a/docs/api/peripherals/timer.rst +++ b/docs/api/peripherals/timer.rst @@ -12,7 +12,7 @@ They are all 64-bit generic timers based on 16-bit prescalers and 64-bit auto-re Application Example ------------------- -64-bit hardware timer example: `examples/peripherals/timer_group `_. +64-bit hardware timer example: :example:`peripherals/timer_group`. API Reference ------------- @@ -20,7 +20,7 @@ API Reference Header Files ^^^^^^^^^^^^ - * `components/driver/timer.h `_ + * :component_file:`driver/include/driver/timer.h` Macros ^^^^^^ diff --git a/docs/api/peripherals/uart.rst b/docs/api/peripherals/uart.rst index b00b4e0648..1392361d9f 100644 --- a/docs/api/peripherals/uart.rst +++ b/docs/api/peripherals/uart.rst @@ -11,7 +11,7 @@ Overview Application Example ------------------- -Configure uart settings and install uart driver to read/write using UART0 and UART1 interfaces: `examples/peripherals/uart `_. +Configure uart settings and install uart driver to read/write using UART0 and UART1 interfaces: :example:`peripherals/uart`. API Reference ------------- @@ -19,7 +19,7 @@ API Reference Header Files ^^^^^^^^^^^^ - * `driver/include/driver/uart.h `_ + * :component_file:`driver/include/driver/uart.h` Data Structures ^^^^^^^^^^^^^^^ diff --git a/docs/api/protocols/index.rst b/docs/api/protocols/index.rst index 9a3a9a0c2f..b5572d8cd6 100644 --- a/docs/api/protocols/index.rst +++ b/docs/api/protocols/index.rst @@ -7,4 +7,4 @@ Protocols API mDNS -Example code for this API section is provided in `examples/protocols `_ directory of ESP-IDF repository. +Example code for this API section is provided in :example:`protocols` directory of ESP-IDF examples. diff --git a/docs/api/protocols/mdns.rst b/docs/api/protocols/mdns.rst index 6214883965..1355642de1 100644 --- a/docs/api/protocols/mdns.rst +++ b/docs/api/protocols/mdns.rst @@ -163,7 +163,7 @@ Example of using the methods above: Application Example ------------------- -mDNS server/scanner example: `examples/protocols/mdns `_. +mDNS server/scanner example: :example:`protocols/mdns`. API Reference ------------- @@ -171,7 +171,7 @@ API Reference Header Files ^^^^^^^^^^^^ - * `components/mdns/include/mdns.h `_ + * :component_file:`mdns/include/mdns.h` Macros ^^^^^^ diff --git a/docs/api/storage/index.rst b/docs/api/storage/index.rst index bf21cc9eea..207ad01ccb 100644 --- a/docs/api/storage/index.rst +++ b/docs/api/storage/index.rst @@ -11,4 +11,4 @@ Storage API FAT Filesystem -Example code for this API section is provided in `examples/storage `_ directory of ESP-IDF repository. +Example code for this API section is provided in :example:`storage` directory of ESP-IDF examples. diff --git a/docs/api/storage/nvs_flash.rst b/docs/api/storage/nvs_flash.rst index 9e97c3a811..ce1af94546 100644 --- a/docs/api/storage/nvs_flash.rst +++ b/docs/api/storage/nvs_flash.rst @@ -3,9 +3,9 @@ Application Example ------------------- -Two examples are provided in ESP-IDF `examples/storage `_ directory: +Two examples are provided in :example:`storage` directory of ESP-IDF examples: -`nvs_rw_value `_ +:example:`storage/nvs_rw_value` Demonstrates how to read and write a single integer value using NVS. @@ -13,7 +13,7 @@ Two examples are provided in ESP-IDF `examples/storage `_ +:example:`storage/nvs_rw_blob` Demonstrates how to read and write a single integer value and a blob (binary large object) using NVS to preserve them between ESP32 module restarts. @@ -29,8 +29,8 @@ API Reference Header Files ^^^^^^^^^^^^ - * `nvs_flash/include/nvs_flash.h `_ - * `nvs_flash/include/nvs.h `_ + * :component_file:`nvs_flash/include/nvs_flash.h` + * :component_file:`nvs_flash/include/nvs.h` Macros ^^^^^^ diff --git a/docs/api/storage/spi_flash.rst b/docs/api/storage/spi_flash.rst index 209b413779..ab03b38faa 100644 --- a/docs/api/storage/spi_flash.rst +++ b/docs/api/storage/spi_flash.rst @@ -13,8 +13,8 @@ API Reference Header Files ^^^^^^^^^^^^ - * `spi_flash/include/esp_spi_flash.h `_ - * `spi_flash/include/esp_partition.h `_ + * :component_file:`spi_flash/include/esp_spi_flash.h` + * :component_file:`spi_flash/include/esp_partition.h` Macros ^^^^^^ diff --git a/docs/api/storage/vfs.rst b/docs/api/storage/vfs.rst index d4e5d24ab7..0035229d83 100644 --- a/docs/api/storage/vfs.rst +++ b/docs/api/storage/vfs.rst @@ -13,8 +13,8 @@ API Reference Header Files ^^^^^^^^^^^^ - * `vfs/include/esp_vfs.h `_ - * `vfs/include/esp_vfs_dev.h `_ + * :component_file:`vfs/include/esp_vfs.h` + * :component_file:`vfs/include/esp_vfs_dev.h` Macros ^^^^^^ diff --git a/docs/api/system/deep_sleep.rst b/docs/api/system/deep_sleep.rst index 393d5f025e..87986026df 100644 --- a/docs/api/system/deep_sleep.rst +++ b/docs/api/system/deep_sleep.rst @@ -90,5 +90,5 @@ The following function can be used to enter deep sleep once wakeup sources are c Application Example ------------------- -Implementation of basic functionality of deep sleep is shown in `protocols/sntp `_ example, where ESP module is periodically waken up to retrive time from NTP server. +Implementation of basic functionality of deep sleep is shown in :example:`protocols/sntp` example, where ESP module is periodically waken up to retrive time from NTP server. diff --git a/docs/api/system/index.rst b/docs/api/system/index.rst index f5746f80fd..a7d5d39018 100644 --- a/docs/api/system/index.rst +++ b/docs/api/system/index.rst @@ -12,4 +12,4 @@ System API Logging -Example code for this API section is provided in `examples/system `_ directory of ESP-IDF repository. +Example code for this API section is provided in :example:`system` directory of ESP-IDF examples. diff --git a/docs/api/system/intr_alloc.rst b/docs/api/system/intr_alloc.rst index 4d2f21abac..015cc32cd2 100644 --- a/docs/api/system/intr_alloc.rst +++ b/docs/api/system/intr_alloc.rst @@ -66,7 +66,7 @@ API Reference Header Files ^^^^^^^^^^^^ - * `esp_intr_alloc.h `_ + * :component_file:`esp32/include/esp_intr_alloc.h` Macros diff --git a/docs/api/system/log.rst b/docs/api/system/log.rst index 24d3bef80a..8aadeac095 100644 --- a/docs/api/system/log.rst +++ b/docs/api/system/log.rst @@ -3,11 +3,11 @@ Application Example ------------------- -Log library is commonly used by most of esp-idf components and examples. For demonstration of log functionality check `examples `_ folder of `espressif/esp-idf `_ repository, that among others, contains the following examples: +Log library is commonly used by most of esp-idf components and examples. For demonstration of log functionality check :idf:`examples` folder of `espressif/esp-idf `_ repository, that among others, contains the following examples: -* `system/ota `_ -* `storage/sd_card `_ -* `protocols/https_request `_ +* :example:`system/ota` +* :example:`storage/sd_card` +* :example:`protocols/https_request` API Reference ------------- @@ -15,7 +15,7 @@ API Reference Header Files ^^^^^^^^^^^^ - * `log/include/esp_log.h `_ + * :component_file:`log/include/esp_log.h` Macros ^^^^^^ diff --git a/docs/api/system/mem_alloc.rst b/docs/api/system/mem_alloc.rst index cebea5b8a5..35868f755d 100644 --- a/docs/api/system/mem_alloc.rst +++ b/docs/api/system/mem_alloc.rst @@ -37,8 +37,8 @@ API Reference Header Files ^^^^^^^^^^^^ - * `esp_heap_alloc_caps.h `_ - * `heap_regions.h `_ + * :component_file:`esp32/include/esp_heap_alloc_caps.h` + * :component_file:`freertos/include/freertos/heap_regions.h` Macros diff --git a/docs/api/system/ota.rst b/docs/api/system/ota.rst index ce2fdba635..6ea4ea1f85 100644 --- a/docs/api/system/ota.rst +++ b/docs/api/system/ota.rst @@ -4,7 +4,7 @@ OTA Application Example ------------------- -Demonstration of OTA (over the air) firmware update workflow: `examples/system/ota `_. +Demonstration of OTA (over the air) firmware update workflow: :example:`system/ota`. API Reference ------------- @@ -12,7 +12,7 @@ API Reference Header Files ^^^^^^^^^^^^ - * `app_update/include/esp_ota_ops.h `_ + * :component_file:`app_update/include/esp_ota_ops.h` Macros ^^^^^^ diff --git a/docs/api/system/wdts.rst b/docs/api/system/wdts.rst index 1b476f2f79..e15ff53dd7 100644 --- a/docs/api/system/wdts.rst +++ b/docs/api/system/wdts.rst @@ -59,8 +59,8 @@ API Reference Header Files ^^^^^^^^^^^^ - * `esp32/include/esp_int_wdt.h `_ - * `esp32/include/esp_task_wdt.h `_ + * :component_file:`esp32/include/esp_int_wdt.h` + * :component_file:`esp32/include/esp_task_wdt.h` Functions diff --git a/docs/api/wifi/esp_smartconfig.rst b/docs/api/wifi/esp_smartconfig.rst index 11a6bccbfa..31295a5d45 100644 --- a/docs/api/wifi/esp_smartconfig.rst +++ b/docs/api/wifi/esp_smartconfig.rst @@ -7,7 +7,7 @@ API Reference Header Files ^^^^^^^^^^^^ - * `esp32/include/esp_smartconfig.h `_ + * :component_file:`esp32/include/esp_smartconfig.h` Type Definitions ^^^^^^^^^^^^^^^^ diff --git a/docs/api/wifi/esp_wifi.rst b/docs/api/wifi/esp_wifi.rst index 247ddf7522..042e810e39 100644 --- a/docs/api/wifi/esp_wifi.rst +++ b/docs/api/wifi/esp_wifi.rst @@ -19,7 +19,7 @@ API Reference Header Files ^^^^^^^^^^^^ - * `esp32/include/esp_wifi.h `_ + * :component_file:`esp32/include/esp_wifi.h` Macros ------ diff --git a/docs/api/wifi/index.rst b/docs/api/wifi/index.rst index aecf87fa3b..97165df6b0 100644 --- a/docs/api/wifi/index.rst +++ b/docs/api/wifi/index.rst @@ -8,4 +8,4 @@ Wi-Fi API Smart Config -Example code for this API section is provided in `examples/wifi `_ directory of ESP-IDF repository. +Example code for this API section is provided in :example:`wifi` directory of ESP-IDF examples. diff --git a/docs/build-system.rst b/docs/build-system.rst index 8f43b21176..0973eeb31f 100644 --- a/docs/build-system.rst +++ b/docs/build-system.rst @@ -464,7 +464,7 @@ The file's contents will be added to the .rodata section in flash, and are avail The names are generated from the full name of the file, as given in COMPONENT_EMBED_FILES. Characters /, ., etc. are replaced with underscores. The _binary prefix in the symbol name is added by objcopy and is the same for both text and binary files. -For an example of using this technique, see `examples/protocols/https_request `_ - the certificate file contents are loaded from the text .pem file at compile time. +For an example of using this technique, see :example:`protocols/https_request` - the certificate file contents are loaded from the text .pem file at compile time. Fully Overriding The Component Makefile diff --git a/docs/conf.py b/docs/conf.py index d38d3dee9d..380a643869 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -14,30 +14,21 @@ import sys import os +import re +from subprocess import call, Popen, PIPE +import shlex # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. -#sys.path.insert(0, os.path.abspath('.')) +sys.path.insert(0, os.path.abspath('.')) +from repo_util import run_cmd_get_output # -- Run DoxyGen to prepare XML for Sphinx--------------------------------- # ref. https://github.com/rtfd/readthedocs.org/issues/388 -from subprocess import call, Popen, PIPE -import shlex - call('doxygen') -# -- Function to get output of a command ---------------------------------- -def run_cmd_get_output(cmd): - process = Popen(shlex.split(cmd), stdout=PIPE) - (output, err) = process.communicate() - exit_code = process.wait() - if exit_code != 0: - raise RuntimeError('command line program has failed') - return output - - # -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. @@ -46,7 +37,7 @@ def run_cmd_get_output(cmd): # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['breathe'] +extensions = ['breathe', 'link-roles'] # Breathe extension variables breathe_projects = { "esp32-idf": "xml/" } @@ -73,22 +64,17 @@ copyright = u'2016 - 2017, Espressif' # built documents. # -# Different setup depending if script is running on ReadTheDocs or elsewhere -on_rtd = os.environ.get('READTHEDOCS') == 'True' -if on_rtd: - # The short X.Y version. - # Apparently ReadTheDocs is getting confused by other version / release - # ReadTheDocs is building specific or the latest release from GitHub. - version = '1.0' - release = '1.0' -else: - # This is supposed to be "the short X.Y version", but it's the only version - # visible when you open index.html. - # Display full version to make things less confusing. - # If needed, nearest tag is returned by 'git describe --abbrev=0'. - version = run_cmd_get_output('git describe') - # The full version, including alpha/beta/rc tags. - release = run_cmd_get_output('git describe') +# Readthedocs largely ignores 'version' and 'release', and displays one of +# 'latest', tag name, or branch name, depending on the build type. +# Still, this is useful for non-RTD builds. +# This is supposed to be "the short X.Y version", but it's the only version +# visible when you open index.html. +# Display full version to make things less confusing. +version = run_cmd_get_output('git describe') +# The full version, including alpha/beta/rc tags. +# If needed, nearest tag is returned by 'git describe --abbrev=0'. +release = version +print 'Version: {0} Release: {1}'.format(version, release) # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/docs/contributor-agreement.rst b/docs/contributor-agreement.rst index a7919da8f8..aac25ad4fd 100644 --- a/docs/contributor-agreement.rst +++ b/docs/contributor-agreement.rst @@ -12,8 +12,8 @@ Framework (esp-idf) ("We" or "Us"). The purpose of this contributor agreement ("Agreement") is to clarify and document the rights granted by contributors to Us. To make this -document effective, please follow the instructions at -https://github.com/espressif/esp-idf/blob/master/CONTRIBUTING.rst. +document effective, please follow the instructions at +:idf_file:`CONTRIBUTING.rst` 1. DEFINITIONS ~~~~~~~~~~~~~~ diff --git a/docs/documenting-code.rst b/docs/documenting-code.rst index a73e26de4b..a201dafb8c 100644 --- a/docs/documenting-code.rst +++ b/docs/documenting-code.rst @@ -135,7 +135,7 @@ OK, but I am new to Sphinx! --------------------------- 1. No worries. All the software you need is well documented. It is also open source and free. Start by checking `Sphinx `_ documentation. If you are not clear how to write using rst markup language, see `reStructuredText Primer `_. -2. Check the source files of this documentation to understand what is behind of what you see now on the screen. Sources are maintained on GitHub in `espressif/esp-idf`_ repository in `/docs `_ folder. You can go directly to the source file of this page by scrolling up and clicking the link in the top right corner. When on GitHub, see what's really inside, open source files by clicking ``Raw`` button. +2. Check the source files of this documentation to understand what is behind of what you see now on the screen. Sources are maintained on GitHub in `espressif/esp-idf`_ repository in :idf:`docs` folder. You can go directly to the source file of this page by scrolling up and clicking the link in the top right corner. When on GitHub, see what's really inside, open source files by clicking ``Raw`` button. 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 `_, `Breathe `_ and `Doxygen `_ to build it locally. You would need a Linux machine for that. diff --git a/docs/link-roles.py b/docs/link-roles.py new file mode 100644 index 0000000000..e774721922 --- /dev/null +++ b/docs/link-roles.py @@ -0,0 +1,34 @@ +# based on http://protips.readthedocs.io/link-roles.html + +from docutils import nodes +from repo_util import run_cmd_get_output + +def get_github_rev(): + path = run_cmd_get_output('git rev-parse --short HEAD') + tag = run_cmd_get_output('git describe --exact-match') + print 'Git commit ID: ', path + if len(tag): + print 'Git tag: ', tag + path = tag + return path + + +def setup(app): + baseurl = 'https://github.com/espressif/esp-idf' + rev = get_github_rev() + app.add_role('idf', autolink('{}/tree/{}/%s'.format(baseurl, rev))) + app.add_role('idf_file', autolink('{}/blob/{}/%s'.format(baseurl, rev))) + app.add_role('idf_raw', autolink('{}/raw/{}/%s'.format(baseurl, rev))) + app.add_role('component', autolink('{}/tree/{}/components/%s'.format(baseurl, rev))) + app.add_role('component_file', autolink('{}/blob/{}/components/%s'.format(baseurl, rev))) + app.add_role('component_raw', autolink('{}/raw/{}/components/%s'.format(baseurl, rev))) + app.add_role('example', autolink('{}/tree/{}/examples/%s'.format(baseurl, rev))) + app.add_role('example_file', autolink('{}/blob/{}/examples/%s'.format(baseurl, rev))) + app.add_role('example_raw', autolink('{}/raw/{}/examples/%s'.format(baseurl, rev))) + +def autolink(pattern): + def role(name, rawtext, text, lineno, inliner, options={}, content=[]): + url = pattern % (text,) + node = nodes.reference(rawtext, text, refuri=url, **options) + return [node], [] + return role diff --git a/docs/make-project.rst b/docs/make-project.rst index e72bb81dd0..0bfac801bb 100644 --- a/docs/make-project.rst +++ b/docs/make-project.rst @@ -4,7 +4,7 @@ Build and Flash with Make Finding a project ----------------- -As well as the `esp-idf-template `_ project mentioned in the setup guide, esp-idf comes with some example projects on github in the `examples `_ directory. +As well as the `esp-idf-template `_ project mentioned in the setup guide, ESP-IDF comes with some example projects on github in the :idf:`examples` directory. Once you've found the project you want to work with, change to its directory and you can configure and build it: diff --git a/docs/repo_util.py b/docs/repo_util.py new file mode 100644 index 0000000000..6249c11df1 --- /dev/null +++ b/docs/repo_util.py @@ -0,0 +1,5 @@ +import re +import os + +def run_cmd_get_output(cmd): + return os.popen(cmd).read().strip() diff --git a/docs/windows-setup.rst b/docs/windows-setup.rst index 00205fb78b..996eacee56 100644 --- a/docs/windows-setup.rst +++ b/docs/windows-setup.rst @@ -23,7 +23,7 @@ As an alternative to getting a pre-prepared environment, you can set up the envi * Run through the installer steps, and accept the "Run MSYS2 now" option at the end. A window will open with a MSYS2 terminal. -* The ESP-IDF repository on github contains a script in the tools directory titled ``windows_install_prerequisites.sh``. If you haven't downloaded the ESP-IDF yet, that's OK - you can just `download that one file in Raw format from here `_. Save it somewhere on your computer. +* The ESP-IDF repository on github contains a script in the tools directory titled ``windows_install_prerequisites.sh``. If you haven't downloaded the ESP-IDF yet, that's OK - you can just download that one file in Raw format from here: :idf_raw:`tools/windows/windows_install_prerequisites.sh`. Save it somewhere on your computer. * Type the path to the shell script into the MSYS2 terminal window. You can type it as a normal Windows path, but use forward-slashes instead of back-slashes. ie: ``C:/Users/myuser/Downloads/windows_install_prerequisites.sh``. You can read the script beforehand to check what it does.