arduino/esp8266
1
0
Fork 0
mirror of https://github.com/esp8266/Arduino.git synced 2025-04-19 23:22:16 +03:00
Code

Sphinx syntax fixes (#9180)

Browse Source 
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
This commit is contained in:
Max Prokhorov 2024-07-31 01:28:46 +03:00 committed by GitHub
parent c2f136515a
commit 1b6f815463
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
11 changed files with 81 additions and 71 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/Makefile
View File

@ -2,7 +2,7 @@
# #
# You can set these variables from the command line. # You can set these variables from the command line.
SPHINXOPTS = SPHINXOPTS = -W --keep-going -n
SPHINXBUILD = sphinx-build SPHINXBUILD = sphinx-build
SPHINXPROJ = ESP8266ArduinoCore SPHINXPROJ = ESP8266ArduinoCore
SOURCEDIR = . SOURCEDIR = .

49
doc/boards.rst
View File

@ -39,25 +39,30 @@ Minimal Hardware Setup for Bootloading and Usage
+-----------------+------------+------------------+ +-----------------+------------+------------------+
| GND | | GND | | GND | | GND |
+-----------------+------------+------------------+ +-----------------+------------+------------------+
| TX or GPIO2\* | | RX | | TX or GPIO2 | | |
| [#tx_or_gpio2]_ | RX | |
+-----------------+------------+------------------+ +-----------------+------------+------------------+
| RX | | TX | | RX | | TX |
+-----------------+------------+------------------+ +-----------------+------------+------------------+
| GPIO0 | PullUp | DTR | | GPIO0 | PullUp | DTR |
+-----------------+------------+------------------+ +-----------------+------------+------------------+
| Reset\* | PullUp | RTS | | Reset | | |
| [#reset]_ | PullUp | RTS |
+-----------------+------------+------------------+ +-----------------+------------+------------------+
| GPIO15\* | PullDown | | | GPIO15 | | |
| [#gpio15]_ | PullDown | |
+-----------------+------------+------------------+ +-----------------+------------+------------------+
| CH\_PD | PullUp | | | CH\_PD | | |
| [#ch_pd]_ | PullUp | |
+-----------------+------------+------------------+ +-----------------+------------+------------------+
- Note .. rubric:: Notes
- GPIO15 is also named MTDO
- Reset is also named RSBT or REST (adding PullUp improves the .. [#tx_or_gpio2] GPIO15 is also named MTDO
.. [#reset] Reset is also named RSBT or REST (adding PullUp improves the
stability of the module) stability of the module)
- GPIO2 is alternative TX for the boot loader mode .. [#gpio15] GPIO2 is alternative TX for the boot loader mode
- **Directly connecting a pin to VCC or GND is not a substitute for a .. [#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 PullUp or PullDown resistor, doing this can break upload management
and the serial console, instability has also been noted in some and the serial console, instability has also been noted in some
cases.** cases.**
@ -88,15 +93,16 @@ ESPxx Hardware
+---------------+------------+------------------+ +---------------+------------+------------------+
| GPIO0 | | GND | | GPIO0 | | GND |
+---------------+------------+------------------+ +---------------+------------+------------------+
| Reset | | RTS\* | | Reset | | RTS [#rts]_ |
+---------------+------------+------------------+ +---------------+------------+------------------+
| GPIO15 | PullDown | | | GPIO15 | PullDown | |
+---------------+------------+------------------+ +---------------+------------+------------------+
| CH\_PD | PullUp | | | CH\_PD | PullUp | |
+---------------+------------+------------------+ +---------------+------------+------------------+
- Note .. rubric:: Notes
- if no RTS is used a manual power toggle is needed
.. [#rts] if no RTS is used a manual power toggle is needed
Minimal Hardware Setup for Running only Minimal Hardware Setup for Running only
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -176,7 +182,11 @@ rst cause
boot mode 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 | | 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 | | 7 | 3.3V | 3.3V | 3.3V | SDIO |
+----------+----------+---------+---------+-------------+ +----------+----------+---------+---------+-------------+
note: - number = ((GPIO15 << 2) \| (GPIO0 << 1) \| GPIO2);
Generic ESP8285 Module Generic ESP8285 Module
---------------------- ----------------------
@ -413,14 +422,10 @@ ThaiEasyElec's ESPino
ESPino by ThaiEasyElec using WROOM-02 module from Espressif Systems with 4 MB Flash. ESPino by ThaiEasyElec using WROOM-02 module from Espressif Systems with 4 MB Flash.
We will update an English description soon. - Product page: * 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
http://thaieasyelec.com/products/wireless-modules/wifi-modules/espino-wifi-development-board-detail.html * Schematics: https://downloads.thaieasyelec.com/ETEE052/ETEE052\_ESPino\_Schematic.pdf
- Schematics: * Dimensions: https://downloads.thaieasyelec.com/ETEE052/ETEE052\_ESPino\_Dimension.pdf
www.thaieasyelec.com/downloads/ETEE052/ETEE052\_ESPino\_Schematic.pdf - * Pinouts (Please see pg.8): https://downloads.thaieasyelec.com/ETEE052/ETEE052\_ESPino\_User\_Manual\_TH\_v1\_0\_20160204.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)
WifInfo WifInfo
------- -------

2
doc/conf.py
View File

@ -66,7 +66,7 @@ version = release
# #
# This is also used if you do content translation via gettext catalogs. # This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases. # 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 # List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files. # directories to ignore when looking for source files.

11
doc/esp8266wifi/generic-examples.rst
View File

@ -40,7 +40,8 @@ To get events to work we need to complete just two steps:
1. Declare the event handler in global scope. 1. Declare the event handler in global scope.
.. code:: cpp .. code-block:: cpp
WiFiEventHandler disconnectedEventHandler; WiFiEventHandler disconnectedEventHandler;
Alternatively, it can be declared as ``static`` in both function and global scopes. Alternatively, it can be declared as ``static`` in both function and global scopes.
@ -49,7 +50,8 @@ Alternatively, it can be declared as ``static`` in both function and global scop
2. Select particular event (in this case ``onStationModeDisconnected``). 2. Select particular event (in this case ``onStationModeDisconnected``).
When this event is fired the code will print out information that station has been disconnected: When this event is fired the code will print out information that station has been disconnected:
.. code:: cpp .. code-block:: cpp
disconnectedEventHandler = WiFi.onStationModeDisconnected( disconnectedEventHandler = WiFi.onStationModeDisconnected(
[](auto&& event) { [](auto&& event) {
Serial.println("Station disconnected"); Serial.println("Station disconnected");
@ -57,7 +59,8 @@ Alternatively, it can be declared as ``static`` in both function and global scop
3. Disable ``disconnectedEventHandler``, so the event is no longer handled by our callback: 3. Disable ``disconnectedEventHandler``, so the event is no longer handled by our callback:
.. code:: cpp .. code-block:: cpp
disconnectedEventHandler = nullptr; 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. 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. The complete code, including both methods discussed at the beginning, is provided below.
.. code:: cpp .. code-block:: cpp
#include <ESP8266WiFi.h> #include <ESP8266WiFi.h>

1
doc/esp8266wifi/server-examples.rst
View File

@ -16,7 +16,6 @@ Table of Contents
- `The Page is Served <#the-page-is-served>`__ - `The Page is Served <#the-page-is-served>`__
- `Get it Together <#put-it-together>`__ - `Get it Together <#put-it-together>`__
- `Get it Run <#get-it-run>`__ - `Get it Run <#get-it-run>`__
- `What Else? <#what-else>`__
- `Conclusion <#conclusion>`__ - `Conclusion <#conclusion>`__
The Object The Object

2
doc/faq/a01-espcomm_sync-failed.rst
View File

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

6
doc/faq/a02-my-esp-crashes.rst
View File

@ -5,7 +5,7 @@ My ESP crashes running some code. How to troubleshoot it?
- `Introduction <#introduction>`__ - `Introduction <#introduction>`__
- `What ESP has to Say <#what-esp-has-to-say>`__ - `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>`__ - `Enable compilation warnings <#enable-compilation-warnings>`__
- `What is the Cause of Restart? <#what-is-the-cause-of-restart>`__ - `What is the Cause of Restart? <#what-is-the-cause-of-restart>`__
- `Exception <#exception>`__ - `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 it's about and where it happens, then use `Arduino ESP8266/ESP32
Exception Stack Trace Exception Stack Trace
Decoder <https://github.com/me-no-dev/EspExceptionDecoder>`__ to find Decoder <https://github.com/me-no-dev/EspExceptionDecoder>`__ to find
out in which line of application it is triggered. Please refer to `Check out in which line of application it is triggered. Please refer to
Where the Code Crashes <#check-where-the-code-crashes>`__ point below `Exception decoder <#exception-decoder>`__ point below
for a quick example how to do it. for a quick example how to do it.
**NOTE:** When decoding exceptions be sure to include all lines between **NOTE:** When decoding exceptions be sure to include all lines between

2
doc/faq/a03-library-does-not-work.rst
View File

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

2
doc/mmu.rst
View File

@ -250,5 +250,3 @@ address range of IRAM or DRAM.
uint8_t mmu_set_uint8(void *p8, const uint8_t val); uint8_t mmu_set_uint8(void *p8, const uint8_t val);
uint16_t mmu_set_uint16(uint16_t *p16, const uint16_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); int16_t mmu_set_int16(int16_t *p16, const int16_t val);
::

6
doc/ota_updates/readme.rst
View File

@ -216,7 +216,7 @@ Requirements
Application Example 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 1. Before you begin, please make sure that you have the following software
installed: installed:
@ -336,7 +336,7 @@ Select COM port and baud rate on external terminal program as if you were using
:alt: Termite settings :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 .. figure:: a-ota-external-serial-terminal-output.png
:alt: OTA upload successful - output on an external serial terminal :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, ``ESP8266HTTPUpdateServer`` library,
- NodeMCU 1.0 (ESP-12E Module). - 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 1. Before you begin, please make sure that you have the following
software installed: software installed:

67
tools/boards.txt.py
View File

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