]> granicus.if.org Git - esp-idf/commitdiff
docs: use custom roles to generate GitHub links
authorIvan Grokhotkov <ivan@espressif.com>
Thu, 19 Jan 2017 08:16:06 +0000 (16:16 +0800)
committerIvan Grokhotkov <ivan@espressif.com>
Fri, 20 Jan 2017 09:22:47 +0000 (17:22 +0800)
This change replaces direct links to GitHub master branch with
auto-generated links using docutils custom roles.
These auto-generated links point to the tree or blob for the git commit
ID (or tag) of the repository. This is needed to ensure that links don’t
become broken when files in master branch are moved around or deleted.

The following roles are introduced:

- :idf:`path` - points to directory inside ESP-IDF
- :idf_blob:`path` - points to file inside ESP-IDF
- :idf_raw:`path` - points to raw view of the file inside ESP-IDF
- :component:`path` - points to directory inside ESP-IDF components dir
- :component_blob:`path` - points to file inside ESP-IDF components dir
- :component_raw:`path` - points to raw view of the file inside ESP-IDF
  components dir
- :example:`path` - points to directory inside ESP-IDF examples dir
- :example_blob:`path` - points to file inside ESP-IDF examples dir
- :example_raw:`path` - points to raw view of the file inside ESP-IDF
  examples dir

A check is added to the CI build script, which searches RST files for
presence of hard-coded links (identified by tree/master, blob/master,
or raw/master part of the URL).
This check can be run manually: cd docs && make gh-linkcheck

Additionally, Sphinx linkcheck build type is used to create new CI test,
which check for broken links. This test has to be triggered explicitly,
because including it in normal build process (when the commit is not yet
deployed to Github) will not work. It can be triggered in a regular
fashion using a combination of cron and Curl, similar to stress tests.

52 files changed:
.gitignore
.gitlab-ci.yml
CONTRIBUTING.rst
components/vfs/README.rst
docs/COPYRIGHT.rst
docs/Makefile
docs/api/bluetooth/controller_vhci.rst
docs/api/bluetooth/esp_blufi.rst
docs/api/bluetooth/esp_bt_defs.rst
docs/api/bluetooth/esp_bt_device.rst
docs/api/bluetooth/esp_bt_main.rst
docs/api/bluetooth/esp_gap_ble.rst
docs/api/bluetooth/esp_gatt_defs.rst
docs/api/bluetooth/esp_gattc.rst
docs/api/bluetooth/esp_gatts.rst
docs/api/bluetooth/index.rst
docs/api/ethernet/esp_eth.rst
docs/api/ethernet/index.rst
docs/api/peripherals/gpio.rst
docs/api/peripherals/i2c.rst
docs/api/peripherals/index.rst
docs/api/peripherals/ledc.rst
docs/api/peripherals/pcnt.rst
docs/api/peripherals/rmt.rst
docs/api/peripherals/sigmadelta.rst
docs/api/peripherals/spi_master.rst
docs/api/peripherals/timer.rst
docs/api/peripherals/uart.rst
docs/api/protocols/index.rst
docs/api/protocols/mdns.rst
docs/api/storage/index.rst
docs/api/storage/nvs_flash.rst
docs/api/storage/spi_flash.rst
docs/api/storage/vfs.rst
docs/api/system/deep_sleep.rst
docs/api/system/index.rst
docs/api/system/intr_alloc.rst
docs/api/system/log.rst
docs/api/system/mem_alloc.rst
docs/api/system/ota.rst
docs/api/system/wdts.rst
docs/api/wifi/esp_smartconfig.rst
docs/api/wifi/esp_wifi.rst
docs/api/wifi/index.rst
docs/build-system.rst
docs/conf.py
docs/contributor-agreement.rst
docs/documenting-code.rst
docs/link-roles.py [new file with mode: 0644]
docs/make-project.rst
docs/repo_util.py [new file with mode: 0644]
docs/windows-setup.rst

index f11370493dd6a8892fd8e32b2a64533e26beb5c8..82f7fd3f2b6e39318e28f304d9d3995c6f576c7b 100644 (file)
@@ -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
index 81a8fba4fb17fe75ebd0632f97b7ddc8043f285c..6cbac5874179654302c523c88686b8dccbf44e8d 100644 (file)
@@ -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
index 5810d06b98733a2c960a13c0ae3b80723482d61f..df407050440c362ba5c339fec421d3c2d404ad4c 100644 (file)
@@ -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 <https://github.com/espressif/esp-idf/tree/master/examples>`_.
+* 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?
 
index 2ad7aa7ec207cdd59769ff1994194b862f5fab6b..26d857fc8df514793483a855e7f0786d5bc9118e 100644 (file)
@@ -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 <https://github.com/espressif/esp-idf/blob/master/components/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).
+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:
 
index 67b3d9bf1c1e93fac34b9b0de3da5f34f35f8059..0e0d45720715de9d589beda9cb492039055db799 100644 (file)
@@ -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/
index c04268ff1d9df8f2e5fc4b5d9dfbe8c48cb19908..8076416b781316fa39ead735cd601126a6ac049f 100644 (file)
@@ -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 " \
index dfad1af25e8b52df4f404976316a0bf390eea8fd..35248cbb1e0a9f6ca844fece2deae467cd27a4d6 100644 (file)
@@ -11,9 +11,9 @@ Overview
 Application Example
 -------------------
 
-Check `/examples/bluetooth <https://github.com/espressif/esp-idf/tree/master/examples/bluetooth>`_ folder of `espressif/esp-idf <https://github.com/espressif/esp-idf/>`_ repository, that contains the following example:
+Check :example:`bluetooth` folder in ESP-IDF examples, which contains the following example:
 
-`ble_adv <https://github.com/espressif/esp-idf/blob/master/examples/bluetooth/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 <https://github.com/espressif/esp-idf/blob/master/components/bt/include/bt.h>`_
+  * :component_file:`bt/include/bt.h`
 
 Type Definitions
 ^^^^^^^^^^^^^^^^
index 442e54f5cac531eca7ef6074ef8a0a5da1a280be..5a1b1595a9258571836355a69d0472daad289099 100644 (file)
@@ -11,9 +11,9 @@ Use should concern these things:
 Application Example
 -------------------
 
-Check `/examples/bluetooth <https://github.com/espressif/esp-idf/tree/master/examples/bluetooth>`_ folder of `espressif/esp-idf <https://github.com/espressif/esp-idf>`_ repository, that contains the following example:
+Check :example:`bluetooth` folder in ESP-IDF examples, which contains the following example:
 
-`blufi <https://github.com/espressif/esp-idf/blob/master/examples/bluetooth/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 <https://github.com/espressif/esp-idf/blob/master/components/bt/bluedroid/api/include/esp_blufi_api.h>`_
+  * :component_file:`bt/bluedroid/api/include/esp_blufi_api.h`
 
 Macros
 ^^^^^^
index 217dfb7620bf2dc4b5e102b27b0498b75b8bf598..527fe9359f8151941461f6a22048d2f7c5f7a38e 100644 (file)
@@ -20,7 +20,7 @@ API Reference
 Header Files
 ^^^^^^^^^^^^
 
-  * `bt/bluedroid/api/include/esp_bt_defs.h <https://github.com/espressif/esp-idf/blob/master/components/bt/bluedroid/api/include/esp_bt_defs.h>`_
+  * :component_file:`bt/bluedroid/api/include/esp_bt_defs.h`
 
 
 Macros
index 79c2e9c9bfb7ff21684d34ef5c0dcac3c585ac54..50e9dcf1a064a1d93869426eee5c72af7d0639c4 100644 (file)
@@ -22,7 +22,7 @@ API Reference
 Header Files
 ^^^^^^^^^^^^
 
-  * `bt/bluedroid/api/include/esp_bt_device.h <https://github.com/espressif/esp-idf/blob/master/components/bt/bluedroid/api/include/esp_bt_device.h>`_
+  * :component_file:`bt/bluedroid/api/include/esp_bt_device.h`
 
 
 Macros
index f44dc7eebcef89d35a397464a057c991025e0a38..1c085a1347e0ee47e2a72ac372da527418f2165d 100644 (file)
@@ -20,7 +20,7 @@ API Reference
 Header Files
 ^^^^^^^^^^^^
 
-  * `bt/bluedroid/api/include/esp_bt_main.h <https://github.com/espressif/esp-idf/blob/master/components/bt/bluedroid/api/include/esp_bt_main.h>`_
+  * :component_file:`bt/bluedroid/api/include/esp_bt_main.h`
 
 
 Macros
index f53b8d56ad76fd7a3b96bb842e6685c288125335..9b2fb1ea07154d50a410b954116a3e8bd5ebe744 100644 (file)
@@ -11,11 +11,11 @@ Overview
 Application Example
 -------------------
 
-Check `/examples/bluetooth <https://github.com/espressif/esp-idf/tree/master/examples/bluetooth>`_ folder of `espressif/esp-idf <https://github.com/espressif/esp-idf>`_ repository, that contains the following examples:
+Check :example:`bluetooth` folder in ESP-IDF examples, which contains the following examples:
 
-`gatt_server <https://github.com/espressif/esp-idf/blob/master/examples/bluetooth/gatt_server>`_, `gatt_client <https://github.com/espressif/esp-idf/blob/master/examples/bluetooth/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 <https://github.com/espressif/esp-idf/blob/master/components/bt/bluedroid/api/include/esp_gap_ble_api.h>`_
+  * :component_file:`bt/bluedroid/api/include/esp_gap_ble_api.h`
 
 
 Macros
index 621c6d95e1248031c9e6453d151be2850cad3e5b..11cb6402790cf2ef0b3a15cf526cdbe0dc986360 100644 (file)
@@ -20,7 +20,7 @@ API Reference
 Header Files
 ^^^^^^^^^^^^
 
-  * `bt/bluedroid/api/include/esp_gatt_defs.h <https://github.com/espressif/esp-idf/blob/master/components/bt/bluedroid/api/include/esp_gatt_defs.h>`_
+  * :component_file:`bt/bluedroid/api/include/esp_gatt_defs.h`
 
 
 Macros
index adfc225dfab0ec05284101c8cc1b10bd0e58c6c3..b41c7e09e368b2aa6658d29510e506b4c3053adb 100644 (file)
@@ -11,11 +11,11 @@ Overview
 Application Example
 -------------------
 
-Check `/examples/bluetooth <https://github.com/espressif/esp-idf/tree/master/examples/bluetooth>`_ folder of `espressif/esp-idf <https://github.com/espressif/esp-idf>`_ repository, that contains the following example:
+Check :example:`bluetooth` folder in ESP-IDF examples, which contains the following examples:
 
-`gatt_client <https://github.com/espressif/esp-idf/blob/master/examples/bluetooth/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 <https://github.com/espressif/esp-idf/blob/master/components/bt/bluedroid/api/include/esp_gattc_api.h>`_
+  * :component_file:`bt/bluedroid/api/include/esp_gattc_api.h`
 
 Macros
 ^^^^^^
index 4753490d4d927e39aae4ab15540e659f802cbf0a..8f0414d67fb6e958ab96ce510d064187e24e8ade 100644 (file)
@@ -11,11 +11,11 @@ Overview
 Application Example
 -------------------
 
-Check `/examples/bluetooth <https://github.com/espressif/esp-idf/tree/master/examples/bluetooth>`_ folder of `espressif/esp-idf <https://github.com/espressif/esp-idf>`_ repository, that contains the following example:
+Check :example:`bluetooth` folder in ESP-IDF examples, which contains the following example:
 
-`gatt_server <https://github.com/espressif/esp-idf/blob/master/examples/bluetooth/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 <https://github.com/espressif/esp-idf/blob/master/components/bt/bluedroid/api/include/esp_gatts_api.h>`_
+  * :component_file:`bt/bluedroid/api/include/esp_gatts_api.h`
 
 Macros
 ^^^^^^
index 5a096c75efa4ffd5349698b6ea087f07318b4796..996a26e138d58120e9deb57253e01d53eda1af24 100644 (file)
@@ -9,4 +9,4 @@ Bluetooth API
    Bluetooth LE <bt_le>
 
 
-Example code for this API section is provided in `examples/bluetooth <https://github.com/espressif/esp-idf/tree/master/examples/bluetooth>`_ directory of ESP-IDF repository.
+Example code for this API section is provided in :example:`bluetooth` directory of ESP-IDF examples.
index 5702389af81fba7896e5d0f18cc2dfe94213f9fd..fbecdca3399af431b36f989c484439021c82537a 100644 (file)
@@ -4,7 +4,7 @@ ETHERNET
 Application Example
 -------------------
 
-ethernet example: `examples/ethernet/ethernet <https://github.com/espressif/esp-idf/tree/master/examples/ethernet/ethernet>`_.
+Ethernet example: :example:`ethernet/ethernet`.
 
 API Reference
 -------------
@@ -12,7 +12,7 @@ API Reference
 Header Files
 ^^^^^^^^^^^^
 
-  * `components/ethernet/include/esp_eth.h <https://github.com/espressif/esp-idf/blob/master/components/ethernet/include/esp_eth.h>`_
+  * :component_file:`ethernet/include/esp_eth.h`
 
 Macros
 ^^^^^^
index 31181d23ea55ea4ceba72d57758a9f8b5f76deb2..6e95831d3277ce4e03c02c335a0e6951b73d9c84 100644 (file)
@@ -7,4 +7,4 @@ Ethernet API
    Ethernet <esp_eth>
 
 
-Example code for this API section is provided in `examples/ethernet <https://github.com/espressif/esp-idf/tree/master/examples/ethernet>`_ directory of ESP-IDF repository.
+Example code for this API section is provided in :example:`ethernet` directory of ESP-IDF examples.
index 643eac1f4db527bbb6b7a29276b7f6578a762f59..da3f4607ead6274880be3ecda72508e0c207ceea 100644 (file)
@@ -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 <https://github.com/espressif/esp-idf/tree/master/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 <https://github.com/espressif/esp-idf/blob/master/components/driver/include/driver/gpio.h>`_
+  * :component_file:`driver/include/driver/gpio.h`
 
 Macros
 ^^^^^^
index 93d863da6bda6698e00924395b6fcbc7dd82a6bc..bd30a345d8ac3d118adead7a8f94b7004aa6a7df 100644 (file)
@@ -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 <https://github.com/espressif/esp-idf/tree/master/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 <https://github.com/espressif/esp-idf/blob/master/components/driver/include/driver/i2c.h>`_
+  * :component_file:`driver/include/driver/i2c.h`
 
 Macros
 ^^^^^^
index 147a722fc6625de8220d40607b890b10efed0f41..f3c1dbe4a30325006caa262af607fe1a13f99e27 100644 (file)
@@ -15,4 +15,4 @@ Peripherals API
    Remote Control <rmt>
 
 
-Example code for this API section is provided in `examples/peripherals <https://github.com/espressif/esp-idf/tree/master/examples/peripherals>`_ directory of ESP-IDF repository.
+Example code for this API section is provided in :example:`peripherals` directory of ESP-IDF examples.
index 8c55e2413bc8e1b29a2f7b3ad68f45eb6f8b9e3c..a1a96543dc5997b98e9f641b84ddd174e95bbcb1 100644 (file)
@@ -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 <https://github.com/espressif/esp-idf/tree/master/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 <https://github.com/espressif/esp-idf/blob/master/components/driver/include/driver/ledc.h>`_
+  * :component_file:`driver/include/driver/ledc.h`
 
 Macros
 ^^^^^^
index bf4fcd04063d44af9db44f81bf78ae5582120322..63e6ad64437888ea3bdd68b2d0ca7bdb4c7dd6f5 100644 (file)
@@ -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 <https://github.com/espressif/esp-idf/tree/master/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 <https://github.com/espressif/esp-idf/blob/master/components/driver/include/driver/pcnt.h>`_
+  * :component_file:`driver/include/driver/pcnt.h`
 
 
 Macros
index 715bc46786e28df086edb929493fb9cad8204737..276ed939e12a7febf36b6f65ab20f5709bd3c367 100644 (file)
@@ -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 <https://github.com/espressif/esp-idf/tree/master/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 <https://github.com/espressif/esp-idf/blob/master/components/driver/include/driver/rmt.h>`_
+  * :component_file:`driver/include/driver/rmt.h`
 
 Macros
 ^^^^^^
index 56e4d77e72829a8bf6c56cfa59df3fb41615b01c..fb51ae8b0366556972d4c767f85c7dac6ef93041 100644 (file)
@@ -10,7 +10,7 @@ This driver configures the channels of the sigma-delta module.
 Application Example
 -------------------
 
-Sigma-delta Modulation example: `examples/peripherals/sigmadelta <https://github.com/espressif/esp-idf/tree/master/examples/peripherals/sigmadelta>`_.
+Sigma-delta Modulation example: :example:`peripherals/sigmadelta`.
 
 API Reference
 -------------
@@ -18,7 +18,7 @@ API Reference
 Header Files
 ^^^^^^^^^^^^
 
-  * `driver/sigmadelta.h <https://github.com/espressif/esp-idf/blob/master/components/driver/include/driver/sigmadelta.h>`_
+  * :component_file:`driver/include/driver/sigmadelta.h`
 
 
 Macros
index 9e5c0eb6369f575ef36d5b9ce41c00f7c434627f..78039cbd79190654e5bf226b36e404b9d0e47b9c 100644 (file)
@@ -108,7 +108,7 @@ as ``tx_data`` and ``rx_data``.
 Application Example
 -------------------
  
-Display graphics on the ILI9341-based 320x240 LCD: `examples/peripherals/spi_master <https://github.com/espressif/esp-idf/tree/master/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 <https://github.com/espressif/esp-idf/blob/master/components/driver/include/driver/spi_master.h>`_
+  * :component_file:`driver/include/driver/spi_master.h`
 
 Macros
 ^^^^^^
index 203c6b0d30772bb55dd444d9116113f75aca17d5..7b5253fde128595e5230de01b58938399a53379f 100644 (file)
@@ -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 <https://github.com/espressif/esp-idf/tree/master/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 <https://github.com/espressif/esp-idf/blob/master/components/driver/include/driver/timer.h>`_
+  * :component_file:`driver/include/driver/timer.h`
 
 Macros
 ^^^^^^
index b00b4e064865ed2721676e5741eeffc0a63efcb2..1392361d9f6d9a71ef904cfee6f8665a615da4da 100644 (file)
@@ -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 <https://github.com/espressif/esp-idf/tree/master/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 <https://github.com/espressif/esp-idf/blob/master/components/driver/include/driver/uart.h>`_
+  * :component_file:`driver/include/driver/uart.h`
 
 Data Structures
 ^^^^^^^^^^^^^^^
index 9a3a9a0c2fa0c4ff5fe335e5e61025a4c556f609..b5572d8cd60d69bfaa61776f4d2181c2b1a7bae9 100644 (file)
@@ -7,4 +7,4 @@ Protocols API
    mDNS <mdns>
 
 
-Example code for this API section is provided in `examples/protocols <https://github.com/espressif/esp-idf/tree/master/examples/protocols>`_ directory of ESP-IDF repository.
+Example code for this API section is provided in :example:`protocols` directory of ESP-IDF examples.
index 621488396551000d52e013cc07e4b9be5a87dc89..1355642de15b4fd30d58bce4e569a3dc1a75d075 100644 (file)
@@ -163,7 +163,7 @@ Example of using the methods above:
 Application Example
 -------------------
 
-mDNS server/scanner example: `examples/protocols/mdns <https://github.com/espressif/esp-idf/tree/master/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 <https://github.com/espressif/esp-idf/blob/master/components/mdns/include/mdns.h>`_
+  * :component_file:`mdns/include/mdns.h`
 
 Macros
 ^^^^^^
index bf21cc9eea03f9448dc5a31cef83e9e70a526a6c..207ad01ccb1290407e4c97428240b1b451163a39 100644 (file)
@@ -11,4 +11,4 @@ Storage API
    FAT Filesystem <fatfs>
 
 
-Example code for this API section is provided in `examples/storage <https://github.com/espressif/esp-idf/tree/master/examples/storage>`_ directory of ESP-IDF repository.
+Example code for this API section is provided in :example:`storage` directory of ESP-IDF examples.
index 9e97c3a8118d26dfb2eebb521a07ffeefc708e1b..ce1af94546971d4fcd94983fd8605496d96ec79c 100644 (file)
@@ -3,9 +3,9 @@
 Application Example
 -------------------
 
-Two examples are provided in ESP-IDF `examples/storage <https://github.com/espressif/esp-idf/tree/master/examples/storage>`_ directory:
+Two examples are provided in :example:`storage` directory of ESP-IDF examples:
 
-`nvs_rw_value <https://github.com/espressif/esp-idf/blob/master/examples/storage/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 <https://github.com/espre
 
   Example also shows how to check if read / write operation was successful, or certain value is not initialized in NVS. Diagnostic is provided in plain text to help track program flow and capture any issues on the way.
 
-`nvs_rw_blob <https://github.com/espressif/esp-idf/blob/master/examples/storage/nvs_rw_blob>`_
+: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 <https://github.com/espressif/esp-idf/blob/master/components/nvs_flash/include/nvs_flash.h>`_
-  * `nvs_flash/include/nvs.h <https://github.com/espressif/esp-idf/blob/master/components/nvs_flash/include/nvs.h>`_
+  * :component_file:`nvs_flash/include/nvs_flash.h`
+  * :component_file:`nvs_flash/include/nvs.h`
 
 Macros
 ^^^^^^
index 209b41377956e5b6530a46174dc620480c5f9cb1..ab03b38faaa3c6032c2c3347042921bb0bd6c94e 100644 (file)
@@ -13,8 +13,8 @@ API Reference
 Header Files
 ^^^^^^^^^^^^
 
-  * `spi_flash/include/esp_spi_flash.h <https://github.com/espressif/esp-idf/blob/master/components/spi_flash/include/esp_spi_flash.h>`_
-  * `spi_flash/include/esp_partition.h <https://github.com/espressif/esp-idf/blob/master/components/spi_flash/include/esp_partition.h>`_
+  * :component_file:`spi_flash/include/esp_spi_flash.h`
+  * :component_file:`spi_flash/include/esp_partition.h`
 
 Macros
 ^^^^^^
index d4e5d24ab77dfa2e32092c464d3d8e1edb66e9c8..0035229d8368258d8774243ed0a6c11fb82259e8 100644 (file)
@@ -13,8 +13,8 @@ API Reference
 Header Files
 ^^^^^^^^^^^^
 
-  * `vfs/include/esp_vfs.h <https://github.com/espressif/esp-idf/blob/master/components/vfs/include/esp_vfs.h>`_
-  * `vfs/include/esp_vfs_dev.h <https://github.com/espressif/esp-idf/blob/master/components/vfs/include/esp_vfs_dev.h>`_
+  * :component_file:`vfs/include/esp_vfs.h`
+  * :component_file:`vfs/include/esp_vfs_dev.h`
 
 Macros
 ^^^^^^
index 393d5f025ed6b0e27c8c1231d9ca70ee75285182..87986026df04695077b3c1a0bffbb8e74d9138f8 100644 (file)
@@ -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 <https://github.com/espressif/esp-idf/tree/master/examples/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.
 
index f5746f80fd06ae011ad8ae520fe65b36b2392e9b..a7d5d3901826b3b3d176218136d9030eecebc9cf 100644 (file)
@@ -12,4 +12,4 @@ System API
    Logging <log>
 
 
-Example code for this API section is provided in `examples/system <https://github.com/espressif/esp-idf/tree/master/examples/system>`_ directory of ESP-IDF repository.
+Example code for this API section is provided in :example:`system` directory of ESP-IDF examples.
index 4d2f21abac0fc25422c320092f4c041a5158ec33..015cc32cd258a6e927583185aa41aef41f37d6e4 100644 (file)
@@ -66,7 +66,7 @@ API Reference
 Header Files
 ^^^^^^^^^^^^
 
-  * `esp_intr_alloc.h <https://github.com/espressif/esp-idf/blob/master/components/esp32/include/esp_intr_alloc.h>`_
+  * :component_file:`esp32/include/esp_intr_alloc.h`
 
 
 Macros
index 24d3bef80a08a5d9939a0de521bfc6ad99a41f62..8aadeac09565baef1c1bf3dc13918a5f18ee8fbe 100644 (file)
@@ -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 <https://github.com/espressif/esp-idf/tree/master/examples>`_ folder of `espressif/esp-idf <https://github.com/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 <https://github.com/espressif/esp-idf>`_ repository, that among others, contains the following examples:
  
-* `system/ota <https://github.com/espressif/esp-idf/tree/master/examples/system/ota>`_ 
-* `storage/sd_card <https://github.com/espressif/esp-idf/tree/master/examples/storage/sd_card>`_ 
-* `protocols/https_request <https://github.com/espressif/esp-idf/tree/master/examples/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 <https://github.com/espressif/esp-idf/blob/master/components/log/include/esp_log.h>`_
+  * :component_file:`log/include/esp_log.h`
 
 Macros
 ^^^^^^
index cebea5b8a55985583de1384263896f379618018d..35868f755dcd362fdbae23809741139e74c11b8a 100644 (file)
@@ -37,8 +37,8 @@ API Reference
 Header Files
 ^^^^^^^^^^^^
 
-  * `esp_heap_alloc_caps.h <https://github.com/espressif/esp-idf/blob/master/components/esp32/include/esp_heap_alloc_caps.h>`_
-  * `heap_regions.h <https://github.com/espressif/esp-idf/blob/master/components/freertos/include/freertos/heap_regions.h>`_
+  * :component_file:`esp32/include/esp_heap_alloc_caps.h`
+  * :component_file:`freertos/include/freertos/heap_regions.h`
 
 
 Macros
index ce2fdba63555ba5464f86b60461283cd909938ca..6ea4ea1f85b177e7217dec87cc9ac627549b0163 100644 (file)
@@ -4,7 +4,7 @@ OTA
 Application Example
 -------------------
  
-Demonstration of OTA (over the air) firmware update workflow: `examples/system/ota <https://github.com/espressif/esp-idf/tree/master/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 <https://github.com/espressif/esp-idf/blob/master/components/app_update/include/esp_ota_ops.h>`_
+  * :component_file:`app_update/include/esp_ota_ops.h`
 
 Macros
 ^^^^^^
index 1b476f2f7959b64c7c61295eb00f2397b74d81d1..e15ff53dd7132db38ecd28d63ec8500259c89af0 100644 (file)
@@ -59,8 +59,8 @@ API Reference
 Header Files
 ^^^^^^^^^^^^
 
-  * `esp32/include/esp_int_wdt.h <https://github.com/espressif/esp-idf/blob/master/components/esp32/include/esp_int_wdt.h>`_
-  * `esp32/include/esp_task_wdt.h <https://github.com/espressif/esp-idf/blob/master/components/esp32/include/esp_task_wdt.h>`_
+  * :component_file:`esp32/include/esp_int_wdt.h`
+  * :component_file:`esp32/include/esp_task_wdt.h`
 
 
 Functions
index 11a6bccbfa37b795bfb6c631a9752d6511e0afe9..31295a5d454d643d5062e27cf669283847bfed09 100644 (file)
@@ -7,7 +7,7 @@ API Reference
 Header Files
 ^^^^^^^^^^^^
 
-  * `esp32/include/esp_smartconfig.h <https://github.com/espressif/esp-idf/blob/master/components/esp32/include/esp_smartconfig.h>`_
+  * :component_file:`esp32/include/esp_smartconfig.h`
 
 Type Definitions
 ^^^^^^^^^^^^^^^^
index 247ddf7522a9f6f8c3067862ba3a000324e9f1ac..042e810e39ea7a97db53dcef3da81fe4864c0df2 100644 (file)
@@ -19,7 +19,7 @@ API Reference
 Header Files
 ^^^^^^^^^^^^
 
-  * `esp32/include/esp_wifi.h <https://github.com/espressif/esp-idf/blob/master/components/esp32/include/esp_wifi.h>`_
+  * :component_file:`esp32/include/esp_wifi.h`
 
 Macros
 ------
index aecf87fa3b515f577f46e52123f77ed5dcf547bf..97165df6b06b541aeb929a97d2bc120f0300ee0e 100644 (file)
@@ -8,4 +8,4 @@ Wi-Fi API
    Smart Config <esp_smartconfig>
 
 
-Example code for this API section is provided in `examples/wifi <https://github.com/espressif/esp-idf/tree/master/examples/wifi>`_ directory of ESP-IDF repository.
+Example code for this API section is provided in :example:`wifi` directory of ESP-IDF examples.
index 8f43b211768257f9ec7000f73078a2a6fab81863..0973eeb31fe4994f0d84712cc11d253bf7638b61 100644 (file)
@@ -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 <https://github.com/espressif/esp-idf/tree/master/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
index d38d3dee9d3aaa6e1bdbc4686ec9783e400f7fee..380a6438699a7cb4ea25faf189661ab3312e9cad 100644 (file)
 
 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.
index a7919da8f8354a5c4d4495df5352d69443bd145c..aac25ad4fd38645e8a15e0ea35ee0b69def984a6 100644 (file)
@@ -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
 ~~~~~~~~~~~~~~
index a73e26de4b9885a3bd5a2cb02b68a6aa069e9795..a201dafb8c194efeb2f3ff6627b1da1372805a8a 100644 (file)
@@ -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 <http://www.sphinx-doc.org/>`_ documentation. If you are not clear how to write using rst markup language, see `reStructuredText Primer <http://www.sphinx-doc.org/en/stable/rest.html>`_.
-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 <https://github.com/espressif/esp-idf/tree/master/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 <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.
diff --git a/docs/link-roles.py b/docs/link-roles.py
new file mode 100644 (file)
index 0000000..e774721
--- /dev/null
@@ -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
index e72bb81dd0db6c465ca994d20cd8e44a68a1c376..0bfac801bbaf7c6666b1097045ca30cd7907a776 100644 (file)
@@ -4,7 +4,7 @@ Build and Flash with Make
 Finding a project
 -----------------
 
-As well as the `esp-idf-template <https://github.com/espressif/esp-idf-template>`_ project mentioned in the setup guide, esp-idf comes with some example projects on github in the `examples <https://github.com/espressif/esp-idf/tree/master/examples>`_ directory.
+As well as the `esp-idf-template <https://github.com/espressif/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 (file)
index 0000000..6249c11
--- /dev/null
@@ -0,0 +1,5 @@
+import re
+import os
+
+def run_cmd_get_output(cmd):
+    return os.popen(cmd).read().strip()
index 00205fb78bb24739b69581f9cd4cdebff96a6713..996eacee56f3102917f93106d8dd029c2498abfd 100644 (file)
@@ -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 <https://github.com/espressif/esp-idf/raw/master/tools/windows/windows_install_prerequisites.sh>`_. 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.