Improve the compatibility of the doc between Github and RTD... (esp82…

…66#4800)

* Update requirements.txt

* Update conf.py

* Update libraries.rst

* Update libraries.rst

* Update libraries.rst

* Update stack_dump.rst

* Update client-examples.rst

* Update readme.rst

* Update readme.rst

* Update server-class.rst

* Update server-examples.rst

* Update soft-access-point-class.rst

* Update station-class.rst

* Update station-examples.rst

* Update udp-class.rst

* Update udp-examples.rst

* Update a04-board-generic-is-unknown.rst

* Update readme.rst

* Update readme.rst

* Update readme.rst

doc/Troubleshooting/stack_dump.rst

@@ -51,7 +51,7 @@ Example:
     <<<stack<<<
 
 The first number after ``Exception`` gives the cause of the reset. a
-full ist of all causes can be found :doc:`here <../exception_causes>`
+full ist of all causes can be found `here <../exception_causes.rst>`__
 the hex after are the stack dump.
 
 Decode

doc/conf.py

@@ -30,8 +30,10 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
-
+extensions = [
+    'nbsphinx',
+    'sphinx.ext.mathjax',
+]
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 

doc/esp8266wifi/client-examples.rst

@@ -249,7 +249,7 @@ In case server's web address is incorrect, or server is not accessible, you shou
 Conclusion
 ~~~~~~~~~~
 
-With this simple example we have demonstrated how to set up a client program, connect it to a server, request a web page and retrieve it. Now you should be able to write your own client program for ESP8266 and move to more advanced dialogue with a server, like e.g. using `HTTPS <https://en.wikipedia.org/wiki/HTTPS>`__ protocol with the :doc:`Client Secure <client-secure-examples>` .
+With this simple example we have demonstrated how to set up a client program, connect it to a server, request a web page and retrieve it. Now you should be able to write your own client program for ESP8266 and move to more advanced dialogue with a server, like e.g. using `HTTPS <https://en.wikipedia.org/wiki/HTTPS>`__ protocol with the `Client Secure <client-secure-examples.rst>`__ .
 
 For more client examples please check
 

doc/esp8266wifi/readme.rst

@@ -51,7 +51,6 @@ In the line ``WiFi.begin("network-name", "pass-to-network")`` replace ``network-
 .. figure:: pictures/wifi-simple-connect-terminal.png
    :alt: Connection log on Arduino IDE's Serial Monitor
 
-   alt text
 
 How does it work? In the first line of sketch ``#include <ESP8266WiFi.h>`` we are including `ESP8266WiFi <https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WiFi>`__ library. This library provides ESP8266 specific Wi-Fi routines we are calling to connect to network.
 
@@ -95,8 +94,6 @@ ESP8266 module can operate as a station, so we can connect it to the Wi-Fi netwo
 .. figure:: pictures/esp8266-station-soft-access-point.png
    :alt: ESP8266 operating in the Station + Soft Access Point mode
 
-   alt text
-
 The `ESP8266WiFi <https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WiFi>`__ library provides wide collection of C++
 `methods <https://en.wikipedia.org/wiki/Method_(computer_programming)>`__ (functions) and `properties <https://en.wikipedia.org/wiki/Property_(programming)>`__ to configure and operate an ESP8266 module in station and / or soft access point mode. They are described in the following chapters.
 
@@ -108,8 +105,6 @@ The `ESP8266WiFi <https://github.com/esp8266/Arduino/tree/master/libraries/ESP82
 .. figure:: pictures/doxygen-class-index.png
    :alt: Index of classes of ESP8266WiFi library
 
-   alt text
-
 Chapters below describe all function calls (`methods <https://en.wikipedia.org/wiki/Method_(computer_programming)>`__ and `properties <https://en.wikipedia.org/wiki/Property_(programming)>`__ in C++ terms) listed in particular classes of `ESP8266WiFi <https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WiFi>`__. Description is illustrated with application examples and code snippets to show how to use functions in practice. Most of this information is broken up into separate documents. Please follow to access them.
 
 Station
@@ -120,13 +115,11 @@ Station (STA) mode is used to get ESP module connected to a Wi-Fi network establ
 .. figure:: pictures/esp8266-station.png
    :alt: ESP8266 operating in the Station mode
 
-   alt text
-
 Station class has several features to facilitate management of Wi-Fi connection. In case the connection is lost, ESP8266 will automatically reconnect to the last used access point, once it is again available. The same happens on module reboot. This is possible since ESP is saving credentials to last used access point in flash (non-volatile) memory. Using the saved data ESP will also reconnect if sketch has been changed but code does not alter the Wi-Fi mode or credentials.
 
-:doc:`Station Class documentation <station-class>`
+`Station Class documentation <station-class.rst>`__
 
-Check out separate section with :doc:`examples <station-examples>`.
+Check out separate section with `examples <station-examples.rst>`__.
 
 Soft Access Point
 ~~~~~~~~~~~~~~~~~
@@ -137,24 +130,22 @@ and connects them further to a wired network. ESP8266 can provide similar functi
 .. figure:: pictures/esp8266-soft-access-point.png
    :alt: ESP8266 operating in the Soft Access Point mode
 
-   alt text
-
 The soft-AP mode is often used and an intermediate step before connecting ESP to a Wi-Fi in a station mode. This is when SSID and password to such network is not known upfront. ESP first boots in soft-AP mode, so we can connect to it using a laptop or a mobile phone. Then we are able to provide credentials to the target network. Once done ESP is switched to the station mode and can connect to the target Wi-Fi.
 
 Another handy application of soft-AP mode is to set up `mesh networks <https://en.wikipedia.org/wiki/Mesh_networking>`__. ESP can operate in both soft-AP and Station mode so it can act as a node of a mesh network.
 
-:doc:`Soft Access Point Class documentation <soft-access-point-class>`
+`Soft Access Point Class documentation <soft-access-point-class.rst>`__
 
-Check out separate section with :doc:`examples <soft-access-point-examples>`.
+Check out separate section with `examples <soft-access-point-examples.rst>`__.
 
 Scan
 ~~~~
 
 To connect a mobile phone to a hot spot, you typically open Wi-Fi settings app, list available networks and pick the hot spot you need. Then enter a password (or not) and you are in. You can do the same with ESP. Functionality of scanning for, and listing of available networks in range is implemented by the Scan Class.
 
-:doc:`Scan Class documentation <scan-class>`.
+`Scan Class documentation <scan-class.rst>`__
 
-Check out separate section with :doc:`examples <scan-examples>`.
+Check out separate section with `examples <scan-examples.rst>`__.
 
 Client
 ~~~~~~
@@ -164,10 +155,7 @@ The Client class creates `clients <https://en.wikipedia.org/wiki/Client_(computi
 .. figure:: pictures/esp8266-client.png
    :alt: ESP8266 operating as the Client
 
-   alt text
-
-Check out separate section with :doc:`examples <client-examples>` / :doc:`list of functions
-<client-class>`
+Check out separate section with `examples <client-examples.rst>`__ / `list of functions <client-class.rst>`__
 
 Client Secure
 ~~~~~~~~~~~~~
@@ -177,11 +165,9 @@ The Client Secure is an extension of `Client Class <#client>`__ where connection
 .. figure:: pictures/esp8266-client-secure.png
    :alt: ESP8266 operating as the Client Secure
 
-   alt text
-
 Secure applications have additional memory (and processing) overhead due to the need to run cryptography algorithms. The stronger the certificate's key, the more overhead is needed. In practice it is not possible to run more than a single secure client at a time. The problem concerns RAM memory we can not add, the flash memory size is usually not the issue. If you like to learn how `client secure library <https://github.com/esp8266/Arduino/blob/master/libraries/ESP8266WiFi/src/WiFiClientSecure.h>`__ has been developed, access to what servers have been tested, and how memory limitations have been overcame, read fascinating issue report `#43 <https://github.com/esp8266/Arduino/issues/43>`__.
 
-Check out separate section with :doc:`examples <client-secure-examples>` / :doc:`list of functions <client-secure-class>`
+Check out separate section with `examples <client-secure-examples.rst>`__ / `list of functions <client-secure-class.rst>`__
 
 Server
 ~~~~~~
@@ -191,25 +177,23 @@ The Server Class creates `servers <https://en.wikipedia.org/wiki/Server_(computi
 .. figure:: pictures/esp8266-server.png
    :alt: ESP8266 operating as the Server
 
-   alt text
-
 Clients connect to sever to send and receive data and access provided functionality.
 
-Check out separate section with :doc:`examples <server-examples>` / :doc:`list of functions <server-class>`.
+Check out separate section with `examples <server-examples.rst>`__ / `list of functions <server-class.rst>`__.
 
 UDP
 ~~~
 
 The UDP Class enables the `User Datagram Protocol (UDP) <https://en.wikipedia.org/wiki/User_Datagram_Protocol>`__ messages to be sent and received. The UDP uses a simple "fire and forget" transmission model with no guarantee of delivery, ordering, or duplicate protection. UDP provides checksums for data integrity, and port numbers for addressing different functions at the source and destination of the datagram.
 
-Check out separate section with :doc:`examples <udp-examples>` / :doc:`list of functions <udp-class>`.
+Check out separate section with `examples <udp-examples.rst>`__ / `list of functions <udp-class.rst>`__.
 
 Generic
 ~~~~~~~
 
 There are several functions offered by ESP8266's `SDK <http://bbs.espressif.com/viewtopic.php?f=51&t=1023>`__ and not present in `Arduino WiFi library <https://www.arduino.cc/en/Reference/WiFi>`__. If such function does not fit into one of classes discussed above, it will likely be in Generic Class. Among them is handler to manage Wi-Fi events like connection, disconnection or obtaining an IP, Wi-Fi mode changes, functions to manage module sleep mode, hostname to an IP address resolution, etc.
 
-Check out separate section with :doc:`examples <generic-examples>` / :doc:`list of functions <generic-class>`.
+Check out separate section with `examples <generic-examples.rst>`__ / `list of functions <generic-class.rst>`__.
 
 Diagnostics
 -----------
@@ -271,7 +255,7 @@ Use this function to provide snapshot of Wi-Fi status in these parts of applicat
 Enable Wi-Fi Diagnostic
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-By default the diagnostic output from Wi-Fi libraries is disabled when you call ``Serial.begin``. To enable debug output again, call ``Serial.setDebugOutput(true)``. To redirect debug output to ``Serial1`` instead, call ``Serial1.setDebugOutput(true)``. For additional details regarding diagnostics using serial ports please refer to :doc:`the documentation <../reference>`.
+By default the diagnostic output from Wi-Fi libraries is disabled when you call ``Serial.begin``. To enable debug output again, call ``Serial.setDebugOutput(true)``. To redirect debug output to ``Serial1`` instead, call ``Serial1.setDebugOutput(true)``. For additional details regarding diagnostics using serial ports please refer to `the documentation <../reference.rst>`__.
 
 Below is an example of output for sample sketch discussed in `Quick Start <#quick-start>`__ above with ``Serial.setDebugOutput(true)``:
 
@@ -314,25 +298,17 @@ To make the analysis easier, rather than looking into individual header or sourc
 .. figure:: pictures/doxygen-esp8266wifi-documentation.png
    :alt: Example of documentation prepared by Doxygen
 
-   alt text
-
 The tool crawls through all header and source files collecting information from formatted comment blocks. If developer of particular class annotated the code, you will see it like in examples below.
 
 .. figure:: pictures/doxygen-example-station-begin.png
    :alt: Example of documentation for station begin method by Doxygen
 
-   alt text
-
 .. figure:: pictures/doxygen-example-station-hostname.png
    :alt: Example of documentation for station hostname propert by Doxygen
 
-   alt text
-
 If code is not annotated, you will still see the function prototype including types of arguments, and can use provided links to jump straight to the source code to check it out on your own. Doxygen provides really excellent navigation between members of library.
 
 .. figure:: pictures/doxygen-example-udp-begin.png
    :alt: Example of documentation for UDP begin method (not annotaed in code)by Doxygen
 
-   alt text
-
 Several classes of `ESP8266WiFi <https://github.com/esp8266/Arduino/tree/master/libraries/ESP8266WiFi>`__ are not annotated. When preparing this document, `Doxygen <http://www.stack.nl/~dimitri/doxygen/>`__ has been tremendous help to quickly navigate through almost 30 files that make this library.

doc/esp8266wifi/server-class.rst

@@ -46,4 +46,4 @@ Other Function Calls
 
 Documentation for the above functions is not yet prepared.
 
-For code samples please refer to separate section with :doc:`examples <server-examples>` dedicated specifically to the Server Class.
+For code samples please refer to separate section with `examples <server-examples.rst>`__ dedicated specifically to the Server Class.

doc/esp8266wifi/server-examples.rst

@@ -223,8 +223,6 @@ Enter provided IP address in a web browser. You should see the page served by ES
 .. figure:: pictures/server-browser-output.png
    :alt: Output from server in a web browser
 
-   alt text
-
 The page would be refreshed every 5 seconds. Each time this happens, you should see a request from the client (your web browser) printed out on the serial monitor:
 
 ::
@@ -243,7 +241,7 @@ The page would be refreshed every 5 seconds. Each time this happens, you should
 What Else?
 ~~~~~~~~~~
 
-Looking on :doc:`client examples <client-examples>` you will quickly find out the similarities in protocol to the server. The protocol starts with a header that contains information what communication will be about. It contains what content type is communicated or accepted like ``text/html``. It states whether connection will be kept alive or closed after submission of the header. It contains identification of the sender like ``User-Agent: Mozilla/5.0 (Windows NT 6.1)``, etc.
+Looking on `client examples <client-examples.rst>`__ you will quickly find out the similarities in protocol to the server. The protocol starts with a header that contains information what communication will be about. It contains what content type is communicated or accepted like ``text/html``. It states whether connection will be kept alive or closed after submission of the header. It contains identification of the sender like ``User-Agent: Mozilla/5.0 (Windows NT 6.1)``, etc.
 
 Conclusion
 ~~~~~~~~~~
@@ -252,4 +250,4 @@ The above example shows that a web server on ESP8266 can be set up in almost no
 
 If you like to try another server example, check out `WiFiWebServer.ino <https://github.com/esp8266/Arduino/blob/master/libraries/ESP8266WiFi/examples/WiFiWebServer/WiFiWebServer.ino>`__, that provides functionality of toggling the GPIO pin on and off out of a web browser.
 
-For the list of functions provided to implement and manage servers, please refer to the :doc:`Server Class <server-class>` documentation.
+For the list of functions provided to implement and manage servers, please refer to the `Server Class <server-class.rst>`__ documentation.

doc/esp8266wifi/soft-access-point-class.rst

@@ -224,4 +224,4 @@ Optionally you can use function without any parameters that returns a ``String``
 
     MAC address = 5E:CF:7F:8B:10:13
 
-For code samples please refer to separate section with :doc:`examples <soft-access-point-examples>` dedicated specifically to the Soft Access Point Class.
+For code samples please refer to separate section with `examples <soft-access-point-examples.rst>`__ dedicated specifically to the Soft Access Point Class.

doc/esp8266wifi/station-class.rst

@@ -46,7 +46,7 @@ Table of Contents
 
 Points below provide description and code snippets how to use particular methods.
 
-For more code samples please refer to separate section with :doc:`examples <station-examples>` dedicated specifically to the Station Class.
+For more code samples please refer to separate section with `examples <station-examples.rst>`__ dedicated specifically to the Station Class.
 
 Start Here
 ~~~~~~~~~~

doc/esp8266wifi/station-examples.rst

@@ -19,7 +19,7 @@ Table of Contents
 Introduction
 ~~~~~~~~~~~~
 
-Following the example in\ `Quick Start <readme.rst#quick-start>`__, we would like to go one step further and made ESP connect to next available access point if current connection is lost. This functionality is provided with 'ESP8266WiFiMulti' class and demonstrated in sketch below.
+Following the example in `Quick Start <readme.rst#quick-start>`__, we would like to go one step further and made ESP connect to next available access point if current connection is lost. This functionality is provided with 'ESP8266WiFiMulti' class and demonstrated in sketch below.
 
 .. code:: cpp
 
@@ -202,4 +202,4 @@ I believe the minimalist sketch with ``ESP8266WiFiMulti`` class is a cool exampl
 
 As shown in above example, reconnecting between access points takes time and is not seamless. Therefore, in practical applications, you will likely need to monitor connection status to decide e.g. if you can send the data to external system or should wait until connection is back.
 
-For detailed review of functions provided to manage station mode please refer to the :doc:`Station Class <station-class>` documentation.
+For detailed review of functions provided to manage station mode please refer to the `Station Class <station-class.rst>`__ documentation.

doc/esp8266wifi/udp-class.rst

@@ -33,4 +33,4 @@ Multicast UDP
 
 The ``WiFiUDP`` class supports sending and receiving multicast packets on STA interface. When sending a multicast packet, replace ``udp.beginPacket(addr, port)`` with ``udp.beginPacketMulticast(addr, port, WiFi.localIP())``. When listening to multicast packets, replace ``udp.begin(port)`` with ``udp.beginMulticast(WiFi.localIP(), multicast_ip_addr, port)``. You can use ``udp.destinationIP()`` to tell whether the packet received was sent to the multicast or unicast address.
 
-For code samples please refer to separate section with :doc:`examples <udp-examples>` dedicated specifically to the UDP Class.
+For code samples please refer to separate section with `examples <udp-examples.rst>`__ dedicated specifically to the UDP Class.

doc/esp8266wifi/udp-examples.rst

@@ -171,8 +171,6 @@ What I have entered is shown below:
 .. figure:: pictures/udp-packet-sender.png
    :alt: Testing UDP with packet sender
 
-   alt text
-
 Now click *Send*.
 
 Immediately after that you should see the following on ESP's serial monitor:
@@ -191,4 +189,4 @@ Conclusion
 
 This simple example shows how to send and receive UDP packets between ESP and an external application. Once tested in this minimal set up, you should be able to program ESP to talk to any other UDP device. In case of issues to establish communication with a new device, use the `Packet Sender <https://packetsender.com>`__ or other similar program for troubleshooting
 
-For review of functions provided to send and receive UDP packets, please refer to the :doc:`UDP Class <udp-class>` documentation.
+For review of functions provided to send and receive UDP packets, please refer to the `UDP Class <udp-class.rst>`__ documentation.