Skip to content

Commit 1b6f815

Browse files
mcsprmcspr
authored
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
1 parent c2f1365 commit 1b6f815

11 files changed

+81
-71
lines changed

Diff for: ‎doc/Makefile

+2-2
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
#
33

44
# You can set these variables from the command line.
5-
SPHINXOPTS =
5+
SPHINXOPTS = -W --keep-going -n
66
SPHINXBUILD = sphinx-build
77
SPHINXPROJ = ESP8266ArduinoCore
88
SOURCEDIR = .
@@ -17,4 +17,4 @@ help:
1717
# Catch-all target: route all unknown targets to Sphinx using the new
1818
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
1919
%: Makefile
20-
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

Diff for: ‎doc/boards.rst

+27-22
Original file line numberDiff line numberDiff line change
@@ -39,25 +39,30 @@ Minimal Hardware Setup for Bootloading and Usage
3939
+-----------------+------------+------------------+
4040
| GND | | GND |
4141
+-----------------+------------+------------------+
42-
| TX or GPIO2\* | | RX |
42+
| TX or GPIO2 | | |
43+
| [#tx_or_gpio2]_ | RX | |
4344
+-----------------+------------+------------------+
4445
| RX | | TX |
4546
+-----------------+------------+------------------+
4647
| GPIO0 | PullUp | DTR |
4748
+-----------------+------------+------------------+
48-
| Reset\* | PullUp | RTS |
49+
| Reset | | |
50+
| [#reset]_ | PullUp | RTS |
4951
+-----------------+------------+------------------+
50-
| GPIO15\* | PullDown | |
52+
| GPIO15 | | |
53+
| [#gpio15]_ | PullDown | |
5154
+-----------------+------------+------------------+
52-
| CH\_PD | PullUp | |
55+
| CH\_PD | | |
56+
| [#ch_pd]_ | PullUp | |
5357
+-----------------+------------+------------------+
5458

55-
- Note
56-
- GPIO15 is also named MTDO
57-
- Reset is also named RSBT or REST (adding PullUp improves the
59+
.. rubric:: Notes
60+
61+
.. [#tx_or_gpio2] GPIO15 is also named MTDO
62+
.. [#reset] Reset is also named RSBT or REST (adding PullUp improves the
5863
stability of the module)
59-
- GPIO2 is alternative TX for the boot loader mode
60-
- **Directly connecting a pin to VCC or GND is not a substitute for a
64+
.. [#gpio15] GPIO2 is alternative TX for the boot loader mode
65+
.. [#ch_pd] **Directly connecting a pin to VCC or GND is not a substitute for a
6166
PullUp or PullDown resistor, doing this can break upload management
6267
and the serial console, instability has also been noted in some
6368
cases.**
@@ -88,15 +93,16 @@ ESPxx Hardware
8893
+---------------+------------+------------------+
8994
| GPIO0 | | GND |
9095
+---------------+------------+------------------+
91-
| Reset | | RTS\* |
96+
| Reset | | RTS [#rts]_ |
9297
+---------------+------------+------------------+
9398
| GPIO15 | PullDown | |
9499
+---------------+------------+------------------+
95100
| CH\_PD | PullUp | |
96101
+---------------+------------+------------------+
97102

98-
- Note
99-
- if no RTS is used a manual power toggle is needed
103+
.. rubric:: Notes
104+
105+
.. [#rts] if no RTS is used a manual power toggle is needed
100106
101107
Minimal Hardware Setup for Running only
102108
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -176,7 +182,11 @@ rst cause
176182
boot mode
177183
~~~~~~~~~
178184

179-
the first value respects the pin setup of the Pins 0, 2 and 15.
185+
the first value respects the pin setup of the Pins 0, 2 and 15
186+
187+
.. code-block::
188+
189+
Number = (GPIO15 << 2) | (GPIO0 << 1) | GPIO2
180190
181191
+----------+----------+---------+---------+-------------+
182192
| Number | GPIO15 | GPIO0 | GPIO2 | Mode |
@@ -198,7 +208,6 @@ the first value respects the pin setup of the Pins 0, 2 and 15.
198208
| 7 | 3.3V | 3.3V | 3.3V | SDIO |
199209
+----------+----------+---------+---------+-------------+
200210

201-
note: - number = ((GPIO15 << 2) \| (GPIO0 << 1) \| GPIO2);
202211

203212
Generic ESP8285 Module
204213
----------------------
@@ -413,14 +422,10 @@ ThaiEasyElec's ESPino
413422

414423
ESPino by ThaiEasyElec using WROOM-02 module from Espressif Systems with 4 MB Flash.
415424

416-
We will update an English description soon. - Product page:
417-
http://thaieasyelec.com/products/wireless-modules/wifi-modules/espino-wifi-development-board-detail.html
418-
- Schematics:
419-
www.thaieasyelec.com/downloads/ETEE052/ETEE052\_ESPino\_Schematic.pdf -
420-
Dimensions:
421-
http://thaieasyelec.com/downloads/ETEE052/ETEE052\_ESPino\_Dimension.pdf
422-
- Pinouts:
423-
http://thaieasyelec.com/downloads/ETEE052/ETEE052\_ESPino\_User\_Manual\_TH\_v1\_0\_20160204.pdf (Please see pg. 8)
425+
* 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
426+
* Schematics: https://downloads.thaieasyelec.com/ETEE052/ETEE052\_ESPino\_Schematic.pdf
427+
* Dimensions: https://downloads.thaieasyelec.com/ETEE052/ETEE052\_ESPino\_Dimension.pdf
428+
* Pinouts (Please see pg.8): https://downloads.thaieasyelec.com/ETEE052/ETEE052\_ESPino\_User\_Manual\_TH\_v1\_0\_20160204.pdf
424429

425430
WifInfo
426431
-------

Diff for: ‎doc/conf.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,7 @@
6666
#
6767
# This is also used if you do content translation via gettext catalogs.
6868
# Usually you set "language" from the command line for these cases.
69-
language = None
69+
language = 'en'
7070

7171
# List of patterns, relative to source directory, that match files and
7272
# directories to ignore when looking for source files.

Diff for: ‎doc/esp8266wifi/generic-examples.rst

+7-4
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,8 @@ To get events to work we need to complete just two steps:
4040

4141
1. Declare the event handler in global scope.
4242

43-
.. code:: cpp
43+
.. code-block:: cpp
44+
4445
WiFiEventHandler disconnectedEventHandler;
4546
4647
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
4950
2. Select particular event (in this case ``onStationModeDisconnected``).
5051
When this event is fired the code will print out information that station has been disconnected:
5152

52-
.. code:: cpp
53+
.. code-block:: cpp
54+
5355
disconnectedEventHandler = WiFi.onStationModeDisconnected(
5456
[](auto&& event) {
5557
Serial.println("Station disconnected");
5658
});
5759
5860
3. Disable ``disconnectedEventHandler``, so the event is no longer handled by our callback:
5961

60-
.. code:: cpp
62+
.. code-block:: cpp
63+
6164
disconnectedEventHandler = nullptr;
6265
6366
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
6770

6871
The complete code, including both methods discussed at the beginning, is provided below.
6972

70-
.. code:: cpp
73+
.. code-block:: cpp
7174
7275
#include <ESP8266WiFi.h>
7376

Diff for: ‎doc/esp8266wifi/server-examples.rst

-1
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,6 @@ Table of Contents
1616
- `The Page is Served <#the-page-is-served>`__
1717
- `Get it Together <#put-it-together>`__
1818
- `Get it Run <#get-it-run>`__
19-
- `What Else? <#what-else>`__
2019
- `Conclusion <#conclusion>`__
2120

2221
The Object

Diff for: ‎doc/faq/a01-espcomm_sync-failed.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ I am getting "espcomm\_sync failed" error when trying to upload my ESP. How to r
99
- `Reset Methods <#reset-methods>`__
1010
- `Ck <#ck>`__
1111
- `Nodemcu <#nodemcu>`__
12-
- `I'm Stuck <#im-stuck>`__
12+
- `I'm Stuck <#i-m-stuck>`__
1313
- `Conclusion <#conclusion>`__
1414

1515
Introduction

Diff for: ‎doc/faq/a02-my-esp-crashes.rst

+3-3
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ My ESP crashes running some code. How to troubleshoot it?
55

66
- `Introduction <#introduction>`__
77
- `What ESP has to Say <#what-esp-has-to-say>`__
8-
- `Get Your H/W Right <#get-your-hw-right>`__
8+
- `Get Your H/W Right <#get-your-h-w-right>`__
99
- `Enable compilation warnings <#enable-compilation-warnings>`__
1010
- `What is the Cause of Restart? <#what-is-the-cause-of-restart>`__
1111
- `Exception <#exception>`__
@@ -148,8 +148,8 @@ table to understand what kind of issue it is. If you have no clues what
148148
it's about and where it happens, then use `Arduino ESP8266/ESP32
149149
Exception Stack Trace
150150
Decoder <https://github.com/me-no-dev/EspExceptionDecoder>`__ to find
151-
out in which line of application it is triggered. Please refer to `Check
152-
Where the Code Crashes <#check-where-the-code-crashes>`__ point below
151+
out in which line of application it is triggered. Please refer to
152+
`Exception decoder <#exception-decoder>`__ point below
153153
for a quick example how to do it.
154154

155155
**NOTE:** When decoding exceptions be sure to include all lines between

Diff for: ‎doc/faq/a03-library-does-not-work.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ This Arduino library doesn't work on ESP. How do I make it working?
77
- `Identify the Issues <#identify-the-issues>`__
88
- `Fix it Yourself <#fix-it-yourself>`__
99
- `Compilation Errors <#compilation-errors>`__
10-
- `Exceptions / Watchdog Resets <#exceptions--watchdog-resets>`__
10+
- `Exceptions / Watchdog Resets <#exceptions-watchdog-resets>`__
1111
- `Functionality Issues <#functionality-issues>`__
1212
- `Conclusion <#conclusion>`__
1313

Diff for: ‎doc/mmu.rst

-2
Original file line numberDiff line numberDiff line change
@@ -250,5 +250,3 @@ address range of IRAM or DRAM.
250250
uint8_t mmu_set_uint8(void *p8, const uint8_t val);
251251
uint16_t mmu_set_uint16(uint16_t *p16, const uint16_t val);
252252
int16_t mmu_set_int16(int16_t *p16, const int16_t val);
253-
254-
::

Diff for: ‎doc/ota_updates/readme.rst

+3-3
Original file line numberDiff line numberDiff line change
@@ -216,7 +216,7 @@ Requirements
216216
Application Example
217217
~~~~~~~~~~~~~~~~~~~
218218

219-
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.
219+
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.
220220

221221
1. Before you begin, please make sure that you have the following software
222222
installed:
@@ -336,7 +336,7 @@ Select COM port and baud rate on external terminal program as if you were using
336336
:alt: Termite settings
337337

338338

339-
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):
339+
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):
340340

341341
.. figure:: a-ota-external-serial-terminal-output.png
342342
:alt: OTA upload successful - output on an external serial terminal
@@ -407,7 +407,7 @@ The sample implementation provided below has been done using:
407407
``ESP8266HTTPUpdateServer`` library,
408408
- NodeMCU 1.0 (ESP-12E Module).
409409

410-
You can use another module if it meets previously described `requirements <#basic-requirements>`__.
410+
You can use another module if it meets previously described `requirements <#ota-basic-requirements>`__.
411411

412412
1. Before you begin, please make sure that you have the following
413413
software installed:

Diff for: ‎tools/boards.txt.py

+36-31
Original file line numberDiff line numberDiff line change
@@ -112,25 +112,30 @@
112112
'+-----------------+------------+------------------+',
113113
'| GND | | GND |',
114114
'+-----------------+------------+------------------+',
115-
'| TX or GPIO2\* | | RX |',
115+
'| TX or GPIO2 | | |',
116+
'| [#tx_or_gpio2]_ | RX | |',
116117
'+-----------------+------------+------------------+',
117118
'| RX | | TX |',
118119
'+-----------------+------------+------------------+',
119120
'| GPIO0 | PullUp | DTR |',
120121
'+-----------------+------------+------------------+',
121-
'| Reset\* | PullUp | RTS |',
122+
'| Reset | | |',
123+
'| [#reset]_ | PullUp | RTS |',
122124
'+-----------------+------------+------------------+',
123-
'| GPIO15\* | PullDown | |',
125+
'| GPIO15 | | |',
126+
'| [#gpio15]_ | PullDown | |',
124127
'+-----------------+------------+------------------+',
125-
'| CH\_PD | PullUp | |',
128+
'| CH\\_PD | | |',
129+
'| [#ch_pd]_ | PullUp | |',
126130
'+-----------------+------------+------------------+',
127131
'',
128-
'- Note',
129-
'- GPIO15 is also named MTDO',
130-
'- Reset is also named RSBT or REST (adding PullUp improves the',
132+
'.. rubric:: Notes',
133+
'',
134+
'.. [#tx_or_gpio2] GPIO15 is also named MTDO',
135+
'.. [#reset] Reset is also named RSBT or REST (adding PullUp improves the',
131136
' stability of the module)',
132-
'- GPIO2 is alternative TX for the boot loader mode',
133-
'- **Directly connecting a pin to VCC or GND is not a substitute for a',
137+
'.. [#gpio15] GPIO2 is alternative TX for the boot loader mode',
138+
'.. [#ch_pd] **Directly connecting a pin to VCC or GND is not a substitute for a',
134139
' PullUp or PullDown resistor, doing this can break upload management',
135140
' and the serial console, instability has also been noted in some',
136141
' cases.**',
@@ -161,15 +166,16 @@
161166
'+---------------+------------+------------------+',
162167
'| GPIO0 | | GND |',
163168
'+---------------+------------+------------------+',
164-
'| Reset | | RTS\* |',
169+
'| Reset | | RTS [#rts]_ |',
165170
'+---------------+------------+------------------+',
166171
'| GPIO15 | PullDown | |',
167172
'+---------------+------------+------------------+',
168-
'| CH\_PD | PullUp | |',
173+
'| CH\\_PD | PullUp | |',
169174
'+---------------+------------+------------------+',
170175
'',
171-
'- Note',
172-
'- if no RTS is used a manual power toggle is needed',
176+
'.. rubric:: Notes',
177+
'',
178+
'.. [#rts] if no RTS is used a manual power toggle is needed',
173179
'',
174180
'Minimal Hardware Setup for Running only',
175181
'~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~',
@@ -187,7 +193,7 @@
187193
'+----------+------------+----------------+',
188194
'| GPIO15 | PullDown | |',
189195
'+----------+------------+----------------+',
190-
'| CH\_PD | PullUp | |',
196+
'| CH\\_PD | PullUp | |',
191197
'+----------+------------+----------------+',
192198
'',
193199
'Minimal',
@@ -249,7 +255,11 @@
249255
'boot mode',
250256
'~~~~~~~~~',
251257
'',
252-
'the first value respects the pin setup of the Pins 0, 2 and 15.',
258+
'the first value respects the pin setup of the Pins 0, 2 and 15',
259+
'',
260+
'.. code-block::',
261+
'',
262+
' Number = (GPIO15 << 2) | (GPIO0 << 1) | GPIO2',
253263
'',
254264
'+----------+----------+---------+---------+-------------+',
255265
'| Number | GPIO15 | GPIO0 | GPIO2 | Mode |',
@@ -271,7 +281,6 @@
271281
'| 7 | 3.3V | 3.3V | 3.3V | SDIO |',
272282
'+----------+----------+---------+---------+-------------+',
273283
'',
274-
'note: - number = ((GPIO15 << 2) \| (GPIO0 << 1) \| GPIO2);',
275284
],
276285
}),
277286
( 'esp8285', {
@@ -756,14 +765,10 @@
756765
],
757766
'desc': [ 'ESPino by ThaiEasyElec using WROOM-02 module from Espressif Systems with 4 MB Flash.',
758767
'',
759-
'We will update an English description soon. - Product page:',
760-
'http://thaieasyelec.com/products/wireless-modules/wifi-modules/espino-wifi-development-board-detail.html',
761-
'- Schematics:',
762-
'www.thaieasyelec.com/downloads/ETEE052/ETEE052\_ESPino\_Schematic.pdf -',
763-
'Dimensions:',
764-
'http://thaieasyelec.com/downloads/ETEE052/ETEE052\_ESPino\_Dimension.pdf',
765-
'- Pinouts:',
766-
'http://thaieasyelec.com/downloads/ETEE052/ETEE052\_ESPino\_User\_Manual\_TH\_v1\_0\_20160204.pdf (Please see pg. 8)',
768+
'* 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',
769+
'* Schematics: https://downloads.thaieasyelec.com/ETEE052/ETEE052\\_ESPino\\_Schematic.pdf',
770+
'* Dimensions: https://downloads.thaieasyelec.com/ETEE052/ETEE052\\_ESPino\\_Dimension.pdf',
771+
'* Pinouts (Please see pg.8): https://downloads.thaieasyelec.com/ETEE052/ETEE052\\_ESPino\\_User\\_Manual\\_TH\\_v1\\_0\\_20160204.pdf',
767772
],
768773
}),
769774
( 'wifinfo', {
@@ -1626,13 +1631,13 @@ def all_flash_map ():
16261631
print("generated: flash map config file (in cores/esp8266/FlashMap.h)")
16271632

16281633
return {
1629-
'autoflash': {
1630-
'.menu.eesz.autoflash': 'Mapping defined by Hardware and Sketch',
1631-
'.menu.eesz.autoflash.build.flash_size': '16M',
1632-
'.menu.eesz.autoflash.build.flash_ld': 'eagle.flash.auto.ld',
1633-
'.menu.eesz.autoflash.build.extra_flags': '-DFLASH_MAP_SUPPORT=1',
1634-
'.menu.eesz.autoflash.upload.maximum_size': '1044464',
1635-
},
1634+
'autoflash': collections.OrderedDict([
1635+
('.menu.eesz.autoflash', 'Mapping defined by Hardware and Sketch'),
1636+
('.menu.eesz.autoflash.build.flash_size', '16M'),
1637+
('.menu.eesz.autoflash.build.flash_ld', 'eagle.flash.auto.ld'),
1638+
('.menu.eesz.autoflash.build.extra_flags', '-DFLASH_MAP_SUPPORT=1'),
1639+
('.menu.eesz.autoflash.upload.maximum_size', '1044464')
1640+
]),
16361641
'512K': f512,
16371642
'1M': f1m,
16381643
'2M': f2m,

0 commit comments

Comments
 (0)