Update conf.py from git tag, fix sphinx warnings (esp8266#5716)

Fixes esp8266#5671

Implements https://protips.readthedocs.io/git-tag-version.html

Fix a myriad of minor Sphinx warnings generated in the docs.

Author: earlephilhower

doc/boards.rst

@@ -336,22 +336,22 @@ LOLIN(WEMOS) D1 mini Lite
 -------------------------
 
 Parameters in Arduino IDE:
-~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Card: "WEMOS D1 Mini Lite"
 - Flash Size: "1M (512K SPIFFS)"
 - CPU Frequency: "80 Mhz"
 - Upload Speed: "230400"
 
 Power:
-~~~~~
+~~~~~~
 
 - 5V pin : 4.7V 500mA output when the board is powered by USB ; 3.5V-6V input
 - 3V3 pin : 3.3V 500mA regulated output
 - Digital pins : 3.3V 30mA.
 
 links:
-~~~~~
+~~~~~~
 
 - Product page: https://www.wemos.cc/
 - Board schematic: https://wiki.wemos.cc/_media/products:d1:sch_d1_mini_lite_v1.0.0.pdf

doc/conf.py

@@ -16,6 +16,7 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
+import re
 import os
 import sys
 # sys.path.insert(0, os.path.abspath('.'))
@@ -55,10 +56,10 @@
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
+# Tip from https://protips.readthedocs.io/git-tag-version.html to get version from tag
+release = re.sub('^v', '', os.popen('git describe').read().strip())
 # The short X.Y version.
-version = u'2.5.0-beta3'
-# The full version, including alpha/beta/rc tags.
-release = u'2.5.0-beta3'
+version = release
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

doc/esp8266wifi/bearssl-client-secure-class.rst

@@ -125,22 +125,22 @@ Prior to connecting to a server, the `BearSSL::WiFiClientSecure` needs to be tol
 There are multiple modes to tell BearSSL how to verify the identity of the remote server.  See the `BearSSL_Validation` example for real uses of the following methods:
 
 setInsecure()
-^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^
 
 Don't verify any X509 certificates.  There is no guarantee that the server connected to is the one you think it is in this case, but this call will mimic the behavior of the deprecated axTLS code.
 
-setKnownKey(const BearSSL::PublicKey *pk)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+setKnownKey(const BearSSL::PublicKey \*pk)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Assume the server is using the specific public key.  This does not verify the identity of the server or the X509 certificate it sends, it simply assumes that its public key is the one given.  If the server updates its public key at a later point then connections will fail.
 
-setFingerprint(const uint8_t fp[20]) / setFingerprint(const char *fpStr)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+setFingerprint(const uint8_t fp[20]) / setFingerprint(const char \*fpStr)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Verify the SHA1 fingerprint of the certificate returned matches this one.  If the server certificate changes, it will fail.  If an array of 20 bytes are sent in, it is assumed they are the binary SHA1 values.  If a `char*` string is passed in, it is parsed as a series of human-readable hex values separated by spaces or colons (e.g. `setFingerprint("00:01:02:03:...:1f");`)
 
-setTrustAnchors(BearSSL::X509List *ta)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+setTrustAnchors(BearSSL::X509List \*ta)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Use the passed-in certificate(s) as a trust anchor, accepting remote certificates signed by any of these.  If you have many trust anchors it may make sense to use a `BearSSL::CertStore` because it will only require RAM for a single trust anchor (while the `setTrustAnchors` call requires memory for all certificates in the list).
 
@@ -184,7 +184,7 @@ Sessions (Resuming connections fast)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 setSession(BearSSL::Session &sess)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 If you are connecting to a server repeatedly in a fixed time period (usually 30 or 60 minutes, but normally configurable at the server), a TLS session can be used to cache crypto settings and speed up connections significantly.
 
@@ -193,8 +193,8 @@ Errors
 
 BearSSL can fail in many more unique and interesting ways then the deprecated axTLS.  Use these calls to get more information when something fails.  
 
-getLastSSLError(char *dest = NULL, size_t len = 0)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+getLastSSLError(char \*dest = NULL, size_t len = 0)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Returns the last BearSSL error code encountered and optionally set a user-allocated buffer to a human-readable form of the error.  To only get the last error integer code, just call without any parameters (`int errCode = getLastSSLError();`).
 

doc/esp8266wifi/bearssl-server-secure-class.rst

@@ -17,19 +17,19 @@ TLS servers require a certificate identifying itself and containing its public k
 
 This example command will generate a RSA 2048-bit key and certificate:
 
-.. code::
+.. code:: bash
 
     openssl req -x509 -nodes -newkey rsa:2048 -keyout key.pem -out cert.pem -days 4096
 
 Again, it is up to the application author to generate this certificate and key and keep the private key safe and **private.**
 
-setRSACert(const BearSSL::X509List *chain, const BearSSL::PrivateKey *sk)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+setRSACert(const BearSSL::X509List \*chain, const BearSSL::PrivateKey \*sk)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Sets a RSA certificate and key to be used by the server when connections are received.  Needs to be called before `begin()`
 
-setECCert(const BearSSL::X509List *chain, unsigned cert_issuer_key_type, const BearSSL::PrivateKey *sk)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+setECCert(const BearSSL::X509List \*chain, unsigned cert_issuer_key_type, const BearSSL::PrivateKey \*sk)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Sets an elliptic curve certificate and key for the server.  Needs to be called before `begin()`.
 
@@ -38,7 +38,7 @@ Requiring Client Certificates
 
 TLS servers can request the client to identify itself by transmitting a certificate during handshake.  If the client cannot transmit the certificate, the connection will be dropped by the server.
 
-setClientTrustAnchor(const BearSSL::X509List *client_CA_ta)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+setClientTrustAnchor(const BearSSL::X509List \*client_CA_ta)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Sets the trust anchor (normally a self-signing CA) that all received certificates will be verified against.  Needs to be called before `begin()`.

doc/esp8266wifi/station-class.rst

@@ -442,7 +442,6 @@ Return the status of Wi-Fi connection.
 .. code:: cpp
 
     WiFi.status()
-::
 
 Function returns one of the following connection statuses:
 

doc/faq/a02-my-esp-crashes.rst

@@ -308,9 +308,9 @@ Memory, memory, memory
 Stack
    The amount of stack in the ESP is tiny at only 4KB. For normal developement in large systems, it 
    is good practice to use and abuse the stack, because it is faster for allocation/deallocation, the scope of the object is well defined, and deallocation automatically happens in reverse order as allocation, which means no mem fragmentation. However, with the tiny amount of stack available in the ESP, that practice is not really viable, at least not for big objects.
-      * Large objects that have internally managed memory, such as String, std::string, std::vector, etc, are ok on the stack, because they internally allocate their buffers on the heap.
-      * Large arrays on the stack, such as uint8_t buffer[2048] should be avoided on the stack and be dynamically allocated (consider smart pointers).
-      * Objects that have large data members, such as large arrays, should be avoided on the stack, and be dynamicaly allocated (consider smart pointers).
+   * Large objects that have internally managed memory, such as String, std::string, std::vector, etc, are ok on the stack, because they internally allocate their buffers on the heap.
+   * Large arrays on the stack, such as uint8_t buffer[2048] should be avoided on the stack and be dynamically allocated (consider smart pointers).
+   * Objects that have large data members, such as large arrays, should be avoided on the stack, and be dynamicaly allocated (consider smart pointers).
 
 
 If at the Wall, Enter an Issue Report

doc/gdb.rst

@@ -76,13 +76,13 @@ ELF format version of it (which includes needed debug symbols).
 
 Under Linux these files are stored in ``/tmp/arduino_build_*`` and the following command will help locate the right file for your app:
 
-.. code:: cpp
+.. code:: bash
 
     find /tmp -name "*.elf" -print
 
 Under Windows these files are stored in ``%userprofile%\AppData\Local\Temp\arduino_build_*`` and the following command will help locate the right file for your app:
 
-.. code:: cpp
+.. code:: bash
 
     dir %userprofile%\appdata\*.elf /s/b
 
@@ -98,19 +98,19 @@ directory.
 
 Linux
 
-.. code:: cpp
+.. code:: bash
 
     ~/.arduino15/packages/esp8266/hardware/xtensa-lx106-elf/bin/xtensa-lx106-elf-gdb
 
 Windows (Using Board Manager version)
 
-.. code:: cpp
+.. code:: bash
 
     %userprofile%\AppData\Local\Arduino15\packages\esp8266\tools\xtensa-lx106-elf-gcc\2.5.0-3-20ed2b9\bin\xtensa-lx106-elf-gdb.exe
 
 Windows (Using Git version)
 
-.. code:: cpp
+.. code:: bash
 
     %userprofile%\Documents\Arduino\hardware\esp8266com\esp8266\tools\xtensa-lx106-elf\bin\xtensa-lx106-elf-gdb.exe
 
@@ -124,7 +124,7 @@ Apply the GDB Configurations
 At the ``(gdb)`` prompt, enter the following options to configure GDB for the
 ESP8266 memory map and configuration:
 
-.. code:: cpp
+.. code:: bash
 
     set remote hardware-breakpoint-limit 1
     set remote hardware-watchpoint-limit 1
@@ -142,7 +142,7 @@ ESP8266 memory map and configuration:
 
 Now tell GDB where your compiled ELF file is located:
 
-.. code:: cpp
+.. code:: bash
 
     file /tmp/arduino_build_257110/sketch_dec26a.ino.elf
 
@@ -153,13 +153,13 @@ Once GDB has been configured properly and loaded your debugging symbols, connect
 it to the ESP with the command (replace the ttyUSB0 or COM9 with your ESP's serial
 port):
 
-.. code:: cpp
+.. code:: bash
 
     target remote /dev/ttyUSB0
 
 or
 
-.. code:: cpp
+.. code:: bash
 
     target remote \\.\COM9
 
@@ -191,7 +191,7 @@ Create a new sketch and paste the following code into it:
 Save it and then build and upload to your ESP8266.  On the Serial monitor you
 should see something like
 
-.. code:: cpp
+.. code:: bash
 
     1
     2
@@ -203,7 +203,7 @@ Now close the Serial Monitor.
 
 Open a command prompt and find the ELF file:
 
-.. code:: cpp
+.. code:: bash
 
     earle@server:~$ find /tmp -name "*.elf" -print
     /tmp/arduino_build_257110/testgdb.ino.elf
@@ -215,7 +215,7 @@ the one we just built, ``testgdb.ino.elf``.
 
 Open up the proper ESP8266-specific GDB
 
-.. code:: cpp
+.. code:: bash
 
     earle@server:~$ ~/.arduino15/packages/esp8266/hardware/xtensa-lx106-elf/bin/xtensa-lx106-elf-gdb
     GNU gdb (GDB) 8.2.50.20180723-git
@@ -238,7 +238,7 @@ Open up the proper ESP8266-specific GDB
 We're now at the GDB prompt, but nothing has been set up for the ESP8266
 and no debug information has been loaded.  Cut-and-paste the setup options:
 
-.. code:: cpp
+.. code:: bash
 
     (gdb) set remote hardware-breakpoint-limit 1
     (gdb) set remote hardware-watchpoint-limit 1
@@ -257,14 +257,14 @@ and no debug information has been loaded.  Cut-and-paste the setup options:
 
 And tell GDB where the debugging info ELF file is located:
 
-.. code:: cpp
+.. code:: bash
 
     (gdb) file /tmp/arduino_build_257110/testgdb.ino.elf
     Reading symbols from /tmp/arduino_build_257110/testgdb.ino.elf...done.
 
 Now, connect to the running ESP8266:
 
-.. code:: cpp
+.. code:: bash
 
     (gdb)     target remote /dev/ttyUSB0
     Remote debugging using /dev/ttyUSB0
@@ -279,7 +279,7 @@ output will be displayed on the GDB console..
 
 Continue the running app to see the serial output:
 
-.. code:: cpp
+.. code:: bash
 
     (gdb) cont
     Continuing.
@@ -291,7 +291,8 @@ Continue the running app to see the serial output:
 
 The app is back running and we can stop it at any time using ``Ctrl-C``:
 
-.. code:: cpp 
+.. code:: bash 
+
     113
     ^C
     Program received signal SIGINT, Interrupt.
@@ -301,7 +302,7 @@ The app is back running and we can stop it at any time using ``Ctrl-C``:
 At this point we can set a breakpoint on the main ``loop()`` and restart
 to get into our own code:
 
-.. code:: cpp
+.. code:: bash
 
     (gdb) break loop
     Breakpoint 1 at 0x40202e33: file /home/earle/Arduino/sketch_dec26a/sketch_dec26a.ino, line 10.
@@ -316,7 +317,8 @@ to get into our own code:
 
 Let's examine the local variable:
 
-.. code:: cpp
+.. code:: bash
+
     (gdb) next
     loop () at /home/earle/Arduino/sketch_dec26a/sketch_dec26a.ino:13
     13      Serial.printf("%d\n", cnt++);
@@ -326,7 +328,7 @@ Let's examine the local variable:
 
 And change it:
 
-.. code:: cpp
+.. code:: bash
 
     $2 = 114
     (gdb) set cnt = 2000
@@ -336,7 +338,7 @@ And change it:
 
 And restart the app and see our changes take effect:
 
-.. code:: cpp
+.. code:: bash
 
     (gdb) cont
     Continuing.
@@ -352,7 +354,7 @@ And restart the app and see our changes take effect:
 
 Looks like we left the breakpoint on loop(), let's get rid of it and try again:
 
-.. code:: cpp
+.. code:: bash
 
     (gdb) delete
     Delete all breakpoints? (y or n) y

doc/installing.rst

@@ -48,12 +48,12 @@ Prerequisites
 
 -  Arduino 1.6.8 (or newer, current working version is 1.8.5)
 -  git
--  Python_ 2.7 (http://python.org)
+-  Python 2.7 (http://python.org)
 -  terminal, console, or command prompt (depending on your OS)
 -  Internet connection
 
 Instructions - Windows 10
-~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~
 - First, make sure you don't already have the ESP8266 library installed using the Board Manager (see above)
 
 - Install git for Windows (if not already; see https://git-scm.com/download/win)
@@ -133,7 +133,7 @@ Note that you could, in theory install in ``C:\Program Files (x86)\Arduino\hardw
 
 
 Instructions - Other OS
-~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~
 
 -  Open the console and go to Arduino directory. This can be either your
    *sketchbook* directory (usually ``<Documents>/Arduino``), or the