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

(this time, sphinx was used locally)

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
+work.  For specific boards, defaults can be updated using the `board.txt
-builder.
+generator <faq/a05-board-generator.rst>`__.
 
 CPU Frequency
 ~~~~~~~~~~~~~
@@ -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
+| 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
+  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
+  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
+  flashing from serial port.
-used in conjunction with a flash button on the board (or by driving the ESP
+| When not available, the ``no dtr`` option can be
-dedicated GPIOs to boot in flash mode at power-on).
+  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,7 +105,7 @@ 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.
@@ -112,17 +113,18 @@ 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. 
+There are a number of options.
-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
+- The first (``None``) is explained by itself.
-developper trying to debug some issues.
+- 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.
 
@@ -130,7 +132,7 @@ 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 SACK-OUT (= no Selective ACKnowledgements for OUTput):
-
+     | no better stability with long distance TCP transfers,
-     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
+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
+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
+bytes, but in very specific cases they can be stored in Heap space, or IRAM
-  space (both in RAM).
+space (both in RAM).
 
-``C++ Exceptions``
+C++ Exceptions
-~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~
 
-  -  C++ exceptions are disabled by default.  Consequently the ``new``
+-  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.
 
-  -  Enabled: on this Arduino core, exceptions are possible.  Note that they
+-  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
+-  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
+-  ``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
+-  ``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
+There are a number of available espressif firmwares.  The first / default
-  choice is fine.  Only try with others after reading on the issue tracker
+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
+that something has to be tried with them.  Note that Espressif obsoleted
-  all of them at the time of writing.
+all of them at the time of writing.
 
-``SSL Support``
+SSL Support
-~~~~~~~~~~~~~~~
+~~~~~~~~~~~
 
-  The first and default choice (``All SSL ciphers``) is good.  The second
+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
+option enables only the main ciphers and can be used to lower flash
-  occupation.
+occupation.
 
-``MMU`` (Memory Management Unit)
+MMU (Memory Management Unit)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-  Head to its `specific documentation<mmu.rst>`__.  Note that there is an option
+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
+providing an additional 16KB of IRAM to your application which can be used
-  with ``new`` and ``malloc``.
+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
+On esp82xx architecture, DRAM can be accessed byte by byte, but read-only
-  flash space (``PROGMEM`` variables) and IRAM cannot.  By default they can
+flash space (``PROGMEM`` variables) and IRAM cannot.  By default they can
-  only be safely accessed in a compatible way using special macros
+only be safely accessed in a compatible way using special macros
-  ``pgm_read_some()``.
+``pgm_read_some()``.
 
-  With the non-default option ``Byte/Word access``, an exception manager
+With the non-default option ``Byte/Word access``, an exception manager
-  allows to transparently use them as if they were byte-accessible.  As a
+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
+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.
+illegal ones.  This mode can also be enabled from the MMU options.