documentation: Arduino IDE options: fix hyperlinks and format (#8158)

(this time, sphinx was used locally)
esp8266 · Jun 22, 2021 · d283541 · d283541
1 parent e55dfc3
commit d283541
Showing 1 changed file with 80 additions and 79 deletions.
diff --git a/doc/ideoptions.rst b/doc/ideoptions.rst
@@ -31,8 +31,8 @@ Upload Speed
 This the UART speed setup for flashing the ESP.  It is not related with the
 UART(Serial) speed programmed from inside the sketch, if enabled.  Default
 values are legacy.  The highest speed option (around 1Mbaud) should always
-work.  For specific boards, defaults can be updated using the <boards>.txt
-builder.
+work.  For specific boards, defaults can be updated using the `board.txt
+generator <faq/a05-board-generator.rst>`__.
 
 CPU Frequency
 ~~~~~~~~~~~~~
@@ -42,7 +42,7 @@ Any ESP82xx can run at 80 or 160MHz.
 Crystal Frequency
 ~~~~~~~~~~~~~~~~~
 
-This is the on-board crystal frequency (26 or 40Mhz).  Default is 26MHz. 
+This is the on-board crystal frequency (26 or 40Mhz).  Default is 26MHz.
 But the chip was designed with 40MHz.  It explains the default strange 74880
 baud rate at boot, which is 115200\*26/40 (115200 being quite a lot used
 by default nowadays).
@@ -70,7 +70,7 @@ list, the first one of each size is the default and suitable for many cases.
 Example: ``4MB (FS:2MB OTA:~1019KB)``:
 
 - 4MB is the flash chip size (= 4 MBytes, sometimes oddly noted 32Mbits)
-- ``OTA:~1019KB`` (around 1MB) is used for Over The Air flashing (note that OTA binary can be ``gzip``-ped)
+- ``OTA:~1019KB`` (around 1MB) is used for Over The Air flashing (note that OTA binary can be gzip-ed)
 - ``FS:2MB`` means that 2MBytes are used for an internal filesystem (LittleFS).
 
 Flash Mode
@@ -82,17 +82,18 @@ depending on the flash chips capabilities and how it is connected to the
 esp8266, the fastest mode may not be working.  Note that ESP8285 requires
 the ``DOUT`` mode.
 
-Here is some more insights about that in `esp32 forums<https://www.esp32.com/viewtopic.php?t=1250#p5523>`__.
+Here is some more insights about that in `esp32 forums <https://www.esp32.com/viewtopic.php?t=1250#p5523>`__.
 
 Reset Method
 ~~~~~~~~~~~~
 
-On some boards (commonly NodeMCU, Lolin/Wemos) an electronic trick allows to
-use the UART DTR line to reset the esp8266 *and* put it in flash mode.  This
-is the default ``dtr/nodemcu`` option.  It provides an extra-easy way of
-flashing from serial port.  When not available, the ``no dtr`` option can be
-used in conjunction with a flash button on the board (or by driving the ESP
-dedicated GPIOs to boot in flash mode at power-on).
+| On some boards (commonly NodeMCU, Lolin/Wemos) an electronic trick allows to
+  use the UART DTR line to reset the esp8266 *and* put it in flash mode.  This
+  is the default ``dtr (aka nodemcu)`` option.  It provides an extra-easy way of
+  flashing from serial port.
+| When not available, the ``no dtr`` option can be
+  used in conjunction with a flash button on the board (or by driving the ESP
+  dedicated GPIOs to boot in flash mode at power-on).
 
 Debug Port
 ~~~~~~~~~~
@@ -104,33 +105,34 @@ There are three UART options:
 - Serial1
 
 When on ``Serial`` or ``Serial1`` options (see
-`reference<reference.rst#serial>`__), messages are sent at 74880 bauds at
+`reference <reference.rst#serial>`__), messages are sent at 74880 bauds at
 boot time then baud rate is changed to user configuration in sketch.  These
 messages are generated by the internal bootloader.  Subsequent serial data
 are coming either from the firmware, this Arduino core, and user application.
 
 Debug Level
 ~~~~~~~~~~~
 
-There are a number of options.  The first (``None``) is explained by itself. 
-The last (``NoAssert - NDEBUG``) is even quieter than the first (some
-internal guards are skipped to save more flash).
+There are a number of options.
 
-The other ones may be used when asked by a maintainer or if you are a
-developper trying to debug some issues.
+- The first (``None``) is explained by itself.
+- The last (``NoAssert - NDEBUG``) is even quieter than the first (some
+  internal guards are skipped to save more flash).
+- The other ones may be used when asked by a maintainer or if you are a
+  developper trying to debug some issues.
 
 lwIP variant
 ~~~~~~~~~~~~
 
-`lwIP<https://en.wikipedia.org/wiki/LwIP>`__ is the internal network
+`lwIP <https://en.wikipedia.org/wiki/LwIP>`__ is the internal network
 software stack.  It is highly configurable and comes with features that can
 be enabled, at the price of RAM or FLASH space usage.
 
 There are 6 variants.  As always, the first and default option is a good
 compromise.  Note that cores v2.x were or could be using the lwIP-v1 stack.
 Only lwIP-v2 is available on cores v3+.
 
-- ``v2 Lower Memory``
+- v2 Lower Memory
 
   This is lwIP-v2 with MSS=536 bytes.  MSS is TCP's `Maximum Segment Size`,
   and different from MTU (IP's Maximum Transfer Unit) which is always 1480
@@ -142,13 +144,13 @@ Only lwIP-v2 is available on cores v3+.
 
   UDP and other IP protocols are not affected by MSS value.
 
-- ``v2 Higher Bandwidth``
+- v2 Higher Bandwidth
 
   When streaming large amount of data, prefer this option.  It uses more
   memory (MSS=1460) so it allows faster transfers thanks to a smaller number
   of packets providing lower overhead and higher bandwidth.
 
-- ``... (no features)``
+- ... (no features)
 
   Disabled features to get more flash space and RAM for users are:
 
@@ -158,89 +160,88 @@ Only lwIP-v2 is available on cores v3+.
 
   -  No AutoIP (not getting 169.254.x.x on DHCP request when there is no DHCP answer),
 
-  -  No SACK-OUT (= no Selective ACKnowledgements for OUTput):
-
-     no better stability with long distance TCP transfers,
+  -  | No SACK-OUT (= no Selective ACKnowledgements for OUTput):
+     | no better stability with long distance TCP transfers,
 
   -  No listen backlog (no protection against DOS attacks for TCP server).
 
-- ``IPv6 ...``
+- IPv6 ...
 
   With these options, IPv6 is enabled, with features.  It uses about 20-30KB
   of supplementary flash space.
 
-``VTable location``
-~~~~~~~~~~~~~~~~~~~
+VTable location
+~~~~~~~~~~~~~~~
 
-  This is the mechanism used in C++ to support dynamic dispatch of virtual
-  methods.  By default these tables are stored in flash to save precious RAM
-  bytes, but in very specific cases they can be stored in Heap space, or IRAM
-  space (both in RAM).
+This is the mechanism used in C++ to support dynamic dispatch of virtual
+methods.  By default these tables are stored in flash to save precious RAM
+bytes, but in very specific cases they can be stored in Heap space, or IRAM
+space (both in RAM).
 
-``C++ Exceptions``
-~~~~~~~~~~~~~~~~~~
+C++ Exceptions
+~~~~~~~~~~~~~~
 
-  -  C++ exceptions are disabled by default.  Consequently the ``new``
-     operator will cause a general failure and a reboot when memory is full.
+-  C++ exceptions are disabled by default.  Consequently the ``new``
+   operator will cause a general failure and a reboot when memory is full.
 
-     Note that the C-``malloc`` function always returns ``nullptr`` when
-     memory is full.
+   Note that the C-``malloc`` function always returns ``nullptr`` when
+   memory is full.
 
-  -  Enabled: on this Arduino core, exceptions are possible.  Note that they
-     are quite ram and flash consuming.
+-  Enabled: on this Arduino core, exceptions are possible.  Note that they
+   are quite ram and flash consuming.
 
-``Stack protection``
-~~~~~~~~~~~~~~~~~~~~
+Stack protection
+~~~~~~~~~~~~~~~~
 
-  -  This is disabled by default
+-  This is disabled by default
 
-  -  When Enabled, the compiler generated extra code to check for stack
-     overflows.  When this happens, an exception is raised with a message and
-     the ESP reboots.
+-  When Enabled, the compiler generated extra code to check for stack
+   overflows.  When this happens, an exception is raised with a message and
+   the ESP reboots.
 
-``Erase Flash``
-~~~~~~~~~~~~~~~
+Erase Flash
+~~~~~~~~~~~
 
-  -  ``Only sketch``: When WiFi is enabled at boot and persistent WiFi
-     credentials are enabled, these data are preserved across flashings.
-     Filesystem is preserved.
+-  ``Only sketch``: When WiFi is enabled at boot and persistent WiFi
+   credentials are enabled, these data are preserved across flashings.
+   Filesystem is preserved.
 
-  -  ``Sketch + WiFi settings``: persistent WiFi settings are not
-     preserved accross flashings. Filesystem is preserved.
+-  ``Sketch + WiFi settings``: persistent WiFi settings are not
+   preserved accross flashings. Filesystem is preserved.
 
-  -  ``All Flash``: WiFi settings and Filesystems are erased.
+-  ``All Flash``: WiFi settings and Filesystems are erased.
 
-``Espressif Firmware``
-~~~~~~~~~~~~~~~~~~~~~~
+Espressif Firmware
+~~~~~~~~~~~~~~~~~~
 
-  There are a number of available espressif firmwares.  The first / default
-  choice is fine.  Only try with others after reading on the issue tracker
-  that something has to be tried with them.  Note that Espressif obsoleted
-  all of them at the time of writing.
+There are a number of available espressif firmwares.  The first / default
+choice is fine.  Only try with others after reading on the issue tracker
+that something has to be tried with them.  Note that Espressif obsoleted
+all of them at the time of writing.
 
-``SSL Support``
-~~~~~~~~~~~~~~~
+SSL Support
+~~~~~~~~~~~
 
-  The first and default choice (``All SSL ciphers``) is good.  The second
-  option enables only the main ciphers and can be used to lower flash
-  occupation.
+The first and default choice (``All SSL ciphers``) is good.  The second
+option enables only the main ciphers and can be used to lower flash
+occupation.
 
-``MMU`` (Memory Management Unit)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+MMU (Memory Management Unit)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-  Head to its `specific documentation<mmu.rst>`__.  Note that there is an option
-  providing an additional 16KB of IRAM to your application which can be used
-  with ``new`` and ``malloc``.
+Head to its `specific documentation <mmu.rst>`__.  Note that there is an option
+providing an additional 16KB of IRAM to your application which can be used
+with ``new`` and ``malloc``.
 
-``Non-32-Bit Access``
-~~~~~~~~~~~~~~~~~~~~~
+Non-32-Bit Access
+~~~~~~~~~~~~~~~~~
 
-  On esp82xx architecture, DRAM can be accessed byte by byte, but read-only
-  flash space (``PROGMEM`` variables) and IRAM cannot.  By default they can
-  only be safely accessed in a compatible way using special macros
-  ``pgm_read_some()``.
+On esp82xx architecture, DRAM can be accessed byte by byte, but read-only
+flash space (``PROGMEM`` variables) and IRAM cannot.  By default they can
+only be safely accessed in a compatible way using special macros
+``pgm_read_some()``.
 
-  With the non-default option ``Byte/Word access``, an exception manager
-  allows to transparently use them as if they were byte-accessible.  As a
-  result, any type of access works but in a very slow way for the usually
-  illegal ones.  This mode can also be enabled from the ``MMU`` options.
+With the non-default option ``Byte/Word access``, an exception manager
+allows to transparently use them as if they were byte-accessible.  As a
+result, any type of access works but in a very slow way for the usually
+illegal ones.  This mode can also be enabled from the MMU options.