Sphinx syntax fixes (#9180)

get rid of warnings when converting python -> rst, force quit when they happen fix code-blocks, always need extra line fix invalid headers refs so they actually work
esp8266 · Jul 30, 2024 · 1b6f815 · 1b6f815
1 parent c2f1365
commit 1b6f815
Show file tree

Hide file tree

Showing 11 changed files with 81 additions and 71 deletions.
diff --git a/doc/Makefile b/doc/Makefile
@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
+SPHINXOPTS    = -W --keep-going -n
 SPHINXBUILD   = sphinx-build
 SPHINXPROJ    = ESP8266ArduinoCore
 SOURCEDIR     = .
@@ -17,4 +17,4 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/doc/boards.rst b/doc/boards.rst
@@ -39,25 +39,30 @@ Minimal Hardware Setup for Bootloading and Usage
 +-----------------+------------+------------------+
 | GND             |            | GND              |
 +-----------------+------------+------------------+
-| TX or GPIO2\*   |            | RX               |
+| TX or GPIO2     |            |                  |
+| [#tx_or_gpio2]_ | RX         |                  |
 +-----------------+------------+------------------+
 | RX              |            | TX               |
 +-----------------+------------+------------------+
 | GPIO0           | PullUp     | DTR              |
 +-----------------+------------+------------------+
-| Reset\*         | PullUp     | RTS              |
+| Reset           |            |                  |
+| [#reset]_       | PullUp     | RTS              |
 +-----------------+------------+------------------+
-| GPIO15\*        | PullDown   |                  |
+| GPIO15          |            |                  |
+| [#gpio15]_      | PullDown   |                  |
 +-----------------+------------+------------------+
-| CH\_PD          | PullUp     |                  |
+| CH\_PD          |            |                  |
+| [#ch_pd]_       | PullUp     |                  |
 +-----------------+------------+------------------+
 
--  Note
--  GPIO15 is also named MTDO
--  Reset is also named RSBT or REST (adding PullUp improves the
+.. rubric:: Notes
+
+.. [#tx_or_gpio2] GPIO15 is also named MTDO
+.. [#reset] Reset is also named RSBT or REST (adding PullUp improves the
    stability of the module)
--  GPIO2 is alternative TX for the boot loader mode
--  **Directly connecting a pin to VCC or GND is not a substitute for a
+.. [#gpio15] GPIO2 is alternative TX for the boot loader mode
+.. [#ch_pd] **Directly connecting a pin to VCC or GND is not a substitute for a
    PullUp or PullDown resistor, doing this can break upload management
    and the serial console, instability has also been noted in some
    cases.**
@@ -88,15 +93,16 @@ ESPxx Hardware
 +---------------+------------+------------------+
 | GPIO0         |            | GND              |
 +---------------+------------+------------------+
-| Reset         |            | RTS\*            |
+| Reset         |            | RTS [#rts]_      |
 +---------------+------------+------------------+
 | GPIO15        | PullDown   |                  |
 +---------------+------------+------------------+
 | CH\_PD        | PullUp     |                  |
 +---------------+------------+------------------+
 
--  Note
--  if no RTS is used a manual power toggle is needed
+.. rubric:: Notes
+
+.. [#rts] if no RTS is used a manual power toggle is needed
 
 Minimal Hardware Setup for Running only
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -176,7 +182,11 @@ rst cause
 boot mode
 ~~~~~~~~~
 
-the first value respects the pin setup of the Pins 0, 2 and 15.
+the first value respects the pin setup of the Pins 0, 2 and 15
+
+.. code-block::
+
+    Number = (GPIO15 << 2) | (GPIO0 << 1) | GPIO2
 
 +----------+----------+---------+---------+-------------+
 | Number   | GPIO15   | GPIO0   | GPIO2   | Mode        |
@@ -198,7 +208,6 @@ the first value respects the pin setup of the Pins 0, 2 and 15.
 | 7        | 3.3V     | 3.3V    | 3.3V    | SDIO        |
 +----------+----------+---------+---------+-------------+
 
-note: - number = ((GPIO15 << 2) \| (GPIO0 << 1) \| GPIO2);
 
 Generic ESP8285 Module
 ----------------------
@@ -413,14 +422,10 @@ ThaiEasyElec's ESPino
 
 ESPino by ThaiEasyElec using WROOM-02 module from Espressif Systems with 4 MB Flash.
 
-We will update an English description soon. - Product page:
-http://thaieasyelec.com/products/wireless-modules/wifi-modules/espino-wifi-development-board-detail.html
-- Schematics:
-www.thaieasyelec.com/downloads/ETEE052/ETEE052\_ESPino\_Schematic.pdf -
-Dimensions:
-http://thaieasyelec.com/downloads/ETEE052/ETEE052\_ESPino\_Dimension.pdf
-- Pinouts:
-http://thaieasyelec.com/downloads/ETEE052/ETEE052\_ESPino\_User\_Manual\_TH\_v1\_0\_20160204.pdf (Please see pg. 8)
+* Product page (retired product): https://www.thaieasyelec.com/product/%E0%B8%A2%E0%B8%81%E0%B9%80%E0%B8%A5%E0%B8%B4%E0%B8%81%E0%B8%88%E0%B8%B3%E0%B8%AB%E0%B8%99%E0%B9%88%E0%B8%B2%E0%B8%A2-retired-espino-wifi-development-board/11000833173001086
+* Schematics: https://downloads.thaieasyelec.com/ETEE052/ETEE052\_ESPino\_Schematic.pdf
+* Dimensions: https://downloads.thaieasyelec.com/ETEE052/ETEE052\_ESPino\_Dimension.pdf
+* Pinouts (Please see pg.8): https://downloads.thaieasyelec.com/ETEE052/ETEE052\_ESPino\_User\_Manual\_TH\_v1\_0\_20160204.pdf
 
 WifInfo
 -------

diff --git a/doc/conf.py b/doc/conf.py
@@ -66,7 +66,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

diff --git a/doc/esp8266wifi/generic-examples.rst b/doc/esp8266wifi/generic-examples.rst
@@ -40,7 +40,8 @@ To get events to work we need to complete just two steps:
 
 1. Declare the event handler in global scope.
 
-.. code:: cpp
+.. code-block:: cpp
+
     WiFiEventHandler disconnectedEventHandler;
 
 Alternatively, it can be declared as ``static`` in both function and global scopes.
@@ -49,15 +50,17 @@ Alternatively, it can be declared as ``static`` in both function and global scop
 2. Select particular event (in this case ``onStationModeDisconnected``).
    When this event is fired the code will print out information that station has been disconnected:
 
-.. code:: cpp
+.. code-block:: cpp
+
     disconnectedEventHandler = WiFi.onStationModeDisconnected(
         [](auto&& event) {
             Serial.println("Station disconnected");
         });
 
 3. Disable ``disconnectedEventHandler``, so the event is no longer handled by our callback:
 
-.. code:: cpp
+.. code-block:: cpp
+
     disconnectedEventHandler = nullptr;
 
 Take note that lifetime of the callback handler is up to the app. e.g. if ``onStationModeDisconnected`` is declared in the function scope, it would be discarded immediately after the function exits.
@@ -67,7 +70,7 @@ The Code
 
 The complete code, including both methods discussed at the beginning, is provided below.
 
-.. code:: cpp
+.. code-block:: cpp
 
     #include <ESP8266WiFi.h>
 

diff --git a/doc/esp8266wifi/server-examples.rst b/doc/esp8266wifi/server-examples.rst
@@ -16,7 +16,6 @@ Table of Contents
 -  `The Page is Served <#the-page-is-served>`__
 -  `Get it Together <#put-it-together>`__
 -  `Get it Run <#get-it-run>`__
--  `What Else? <#what-else>`__
 -  `Conclusion <#conclusion>`__
 
 The Object

diff --git a/doc/faq/a01-espcomm_sync-failed.rst b/doc/faq/a01-espcomm_sync-failed.rst
@@ -9,7 +9,7 @@ I am getting "espcomm\_sync failed" error when trying to upload my ESP. How to r
 -  `Reset Methods <#reset-methods>`__
 -  `Ck <#ck>`__
 -  `Nodemcu <#nodemcu>`__
--  `I'm Stuck <#im-stuck>`__
+-  `I'm Stuck <#i-m-stuck>`__
 -  `Conclusion <#conclusion>`__
 
 Introduction

diff --git a/doc/faq/a02-my-esp-crashes.rst b/doc/faq/a02-my-esp-crashes.rst
@@ -5,7 +5,7 @@ My ESP crashes running some code. How to troubleshoot it?
 
 -  `Introduction <#introduction>`__
 -  `What ESP has to Say <#what-esp-has-to-say>`__
--  `Get Your H/W Right <#get-your-hw-right>`__
+-  `Get Your H/W Right <#get-your-h-w-right>`__
 -  `Enable compilation warnings <#enable-compilation-warnings>`__
 -  `What is the Cause of Restart? <#what-is-the-cause-of-restart>`__
 -  `Exception <#exception>`__
@@ -148,8 +148,8 @@ table to understand what kind of issue it is. If you have no clues what
 it's about and where it happens, then use `Arduino ESP8266/ESP32
 Exception Stack Trace
 Decoder <https://github.com/me-no-dev/EspExceptionDecoder>`__ to find
-out in which line of application it is triggered. Please refer to `Check
-Where the Code Crashes <#check-where-the-code-crashes>`__ point below
+out in which line of application it is triggered. Please refer to
+`Exception decoder <#exception-decoder>`__ point below
 for a quick example how to do it.
 
 **NOTE:** When decoding exceptions be sure to include all lines between

diff --git a/doc/faq/a03-library-does-not-work.rst b/doc/faq/a03-library-does-not-work.rst
@@ -7,7 +7,7 @@ This Arduino library doesn't work on ESP. How do I make it working?
 -  `Identify the Issues <#identify-the-issues>`__
 -  `Fix it Yourself <#fix-it-yourself>`__
 -  `Compilation Errors <#compilation-errors>`__
--  `Exceptions / Watchdog Resets <#exceptions--watchdog-resets>`__
+-  `Exceptions / Watchdog Resets <#exceptions-watchdog-resets>`__
 -  `Functionality Issues <#functionality-issues>`__
 -  `Conclusion <#conclusion>`__
 

diff --git a/doc/mmu.rst b/doc/mmu.rst
@@ -250,5 +250,3 @@ address range of IRAM or DRAM.
    uint8_t mmu_set_uint8(void *p8, const uint8_t val);
    uint16_t mmu_set_uint16(uint16_t *p16, const uint16_t val);
    int16_t mmu_set_int16(int16_t *p16, const int16_t val);
-
-::
diff --git a/doc/ota_updates/readme.rst b/doc/ota_updates/readme.rst
@@ -216,7 +216,7 @@ Requirements
 Application Example
 ~~~~~~~~~~~~~~~~~~~
 
-Instructions below show configuration of OTA on a NodeMCU 1.0 (ESP-12E Module) board. You can use any other board that meets the `requirements <#basic-requirements>`__ described above. This instruction is valid for all operating systems supported by the Arduino IDE. Screen captures have been made on Windows 7 and you may see small differences (like name of the serial port), if you are using Linux or MacOS.
+Instructions below show configuration of OTA on a NodeMCU 1.0 (ESP-12E Module) board. You can use any other board that meets the `requirements <#ota-basic-requirements>`__ described above. This instruction is valid for all operating systems supported by the Arduino IDE. Screen captures have been made on Windows 7 and you may see small differences (like name of the serial port), if you are using Linux or MacOS.
 
 1. Before you begin, please make sure that you have the following software
    installed:
@@ -336,7 +336,7 @@ Select COM port and baud rate on external terminal program as if you were using
    :alt: Termite settings
 
 
-Then run OTA from IDE and look what is displayed on terminal. Successful `ArduinoOTA <#arduinoota>`__ process using BasicOTA.ino sketch looks like below (IP address depends on your network configuration):
+Then run OTA from IDE and look what is displayed on terminal. Successful `ArduinoOTA <#arduino-ide>`__ process using BasicOTA.ino sketch looks like below (IP address depends on your network configuration):
 
 .. figure:: a-ota-external-serial-terminal-output.png
    :alt: OTA upload successful - output on an external serial terminal
@@ -407,7 +407,7 @@ The sample implementation provided below has been done using:
    ``ESP8266HTTPUpdateServer`` library,
 -  NodeMCU 1.0 (ESP-12E Module).
 
-You can use another module if it meets previously described `requirements <#basic-requirements>`__.
+You can use another module if it meets previously described `requirements <#ota-basic-requirements>`__.
 
 1. Before you begin, please make sure that you have the following
    software installed:

diff --git a/tools/boards.txt.py b/tools/boards.txt.py
@@ -112,25 +112,30 @@
                   '+-----------------+------------+------------------+',
                   '| GND             |            | GND              |',
                   '+-----------------+------------+------------------+',
-                  '| TX or GPIO2\*   |            | RX               |',
+                  '| TX or GPIO2     |            |                  |',
+                  '| [#tx_or_gpio2]_ | RX         |                  |',
                   '+-----------------+------------+------------------+',
                   '| RX              |            | TX               |',
                   '+-----------------+------------+------------------+',
                   '| GPIO0           | PullUp     | DTR              |',
                   '+-----------------+------------+------------------+',
-                  '| Reset\*         | PullUp     | RTS              |',
+                  '| Reset           |            |                  |',
+                  '| [#reset]_       | PullUp     | RTS              |',
                   '+-----------------+------------+------------------+',
-                  '| GPIO15\*        | PullDown   |                  |',
+                  '| GPIO15          |            |                  |',
+                  '| [#gpio15]_      | PullDown   |                  |',
                   '+-----------------+------------+------------------+',
-                  '| CH\_PD          | PullUp     |                  |',
+                  '| CH\\_PD          |            |                  |',
+                  '| [#ch_pd]_       | PullUp     |                  |',
                   '+-----------------+------------+------------------+',
                   '',
-                  '-  Note',
-                  '-  GPIO15 is also named MTDO',
-                  '-  Reset is also named RSBT or REST (adding PullUp improves the',
+                  '.. rubric:: Notes',
+                  '',
+                  '.. [#tx_or_gpio2] GPIO15 is also named MTDO',
+                  '.. [#reset] Reset is also named RSBT or REST (adding PullUp improves the',
                   '   stability of the module)',
-                  '-  GPIO2 is alternative TX for the boot loader mode',
-                  '-  **Directly connecting a pin to VCC or GND is not a substitute for a',
+                  '.. [#gpio15] GPIO2 is alternative TX for the boot loader mode',
+                  '.. [#ch_pd] **Directly connecting a pin to VCC or GND is not a substitute for a',
                   '   PullUp or PullDown resistor, doing this can break upload management',
                   '   and the serial console, instability has also been noted in some',
                   '   cases.**',
@@ -161,15 +166,16 @@
                   '+---------------+------------+------------------+',
                   '| GPIO0         |            | GND              |',
                   '+---------------+------------+------------------+',
-                  '| Reset         |            | RTS\*            |',
+                  '| Reset         |            | RTS [#rts]_      |',
                   '+---------------+------------+------------------+',
                   '| GPIO15        | PullDown   |                  |',
                   '+---------------+------------+------------------+',
-                  '| CH\_PD        | PullUp     |                  |',
+                  '| CH\\_PD        | PullUp     |                  |',
                   '+---------------+------------+------------------+',
                   '',
-                  '-  Note',
-                  '-  if no RTS is used a manual power toggle is needed',
+                  '.. rubric:: Notes',
+                  '',
+                  '.. [#rts] if no RTS is used a manual power toggle is needed',
                   '',
                   'Minimal Hardware Setup for Running only',
                   '~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~',
@@ -187,7 +193,7 @@
                   '+----------+------------+----------------+',
                   '| GPIO15   | PullDown   |                |',
                   '+----------+------------+----------------+',
-                  '| CH\_PD   | PullUp     |                |',
+                  '| CH\\_PD   | PullUp     |                |',
                   '+----------+------------+----------------+',
                   '',
                   'Minimal',
@@ -249,7 +255,11 @@
                   'boot mode',
                   '~~~~~~~~~',
                   '',
-                  'the first value respects the pin setup of the Pins 0, 2 and 15.',
+                  'the first value respects the pin setup of the Pins 0, 2 and 15',
+                  '',
+                  '.. code-block::',
+                  '',
+                  '    Number = (GPIO15 << 2) | (GPIO0 << 1) | GPIO2',
                   '',
                   '+----------+----------+---------+---------+-------------+',
                   '| Number   | GPIO15   | GPIO0   | GPIO2   | Mode        |',
@@ -271,7 +281,6 @@
                   '| 7        | 3.3V     | 3.3V    | 3.3V    | SDIO        |',
                   '+----------+----------+---------+---------+-------------+',
                   '',
-                  'note: - number = ((GPIO15 << 2) \| (GPIO0 << 1) \| GPIO2);',
                   ],
     }),
     ( 'esp8285', {
@@ -756,14 +765,10 @@
             ],
         'desc': [ 'ESPino by ThaiEasyElec using WROOM-02 module from Espressif Systems with 4 MB Flash.',
                   '',
-                  'We will update an English description soon. - Product page:',
-                  'http://thaieasyelec.com/products/wireless-modules/wifi-modules/espino-wifi-development-board-detail.html',
-                  '- Schematics:',
-                  'www.thaieasyelec.com/downloads/ETEE052/ETEE052\_ESPino\_Schematic.pdf -',
-                  'Dimensions:',
-                  'http://thaieasyelec.com/downloads/ETEE052/ETEE052\_ESPino\_Dimension.pdf',
-                  '- Pinouts:',
-                  'http://thaieasyelec.com/downloads/ETEE052/ETEE052\_ESPino\_User\_Manual\_TH\_v1\_0\_20160204.pdf (Please see pg. 8)',
+                  '* Product page (retired product): https://www.thaieasyelec.com/product/%E0%B8%A2%E0%B8%81%E0%B9%80%E0%B8%A5%E0%B8%B4%E0%B8%81%E0%B8%88%E0%B8%B3%E0%B8%AB%E0%B8%99%E0%B9%88%E0%B8%B2%E0%B8%A2-retired-espino-wifi-development-board/11000833173001086',
+                  '* Schematics: https://downloads.thaieasyelec.com/ETEE052/ETEE052\\_ESPino\\_Schematic.pdf',
+                  '* Dimensions: https://downloads.thaieasyelec.com/ETEE052/ETEE052\\_ESPino\\_Dimension.pdf',
+                  '* Pinouts (Please see pg.8): https://downloads.thaieasyelec.com/ETEE052/ETEE052\\_ESPino\\_User\\_Manual\\_TH\\_v1\\_0\\_20160204.pdf',
                   ],
     }),
     ( 'wifinfo', {
@@ -1626,13 +1631,13 @@ def all_flash_map ():
             print("generated: flash map config file (in cores/esp8266/FlashMap.h)")
 
     return {
-        'autoflash': {
-            '.menu.eesz.autoflash': 'Mapping defined by Hardware and Sketch',
-            '.menu.eesz.autoflash.build.flash_size': '16M',
-            '.menu.eesz.autoflash.build.flash_ld': 'eagle.flash.auto.ld',
-            '.menu.eesz.autoflash.build.extra_flags': '-DFLASH_MAP_SUPPORT=1',
-            '.menu.eesz.autoflash.upload.maximum_size': '1044464',
-        },
+        'autoflash': collections.OrderedDict([
+            ('.menu.eesz.autoflash', 'Mapping defined by Hardware and Sketch'),
+            ('.menu.eesz.autoflash.build.flash_size', '16M'),
+            ('.menu.eesz.autoflash.build.flash_ld', 'eagle.flash.auto.ld'),
+            ('.menu.eesz.autoflash.build.extra_flags', '-DFLASH_MAP_SUPPORT=1'),
+            ('.menu.eesz.autoflash.upload.maximum_size', '1044464')
+        ]),
         '512K': f512,
           '1M':  f1m,
           '2M':  f2m,