Documentation fixes (#2841)

General review and update to documentation

**Smart quotes**

These are the 'pretty' versions of regular quotes which can infect code and documentation due to a 'smart quote' virus embedded into many modern editors.
Their purpose is to make documentation (e.g. web pages) look pretty. That's it.

Their presence in C/C++ code is a syntax errror. In documentation, not so much.
However, if they appear in quoted code snippets then these won't work when pasted.

I think it best therefore to avoid them completely, so have all been converted to standard 'dumb' quotes.

Note that Sphinx will automatically convert regular quotes into their curly equivalents so there is no need whatsoever to have these in the source.

TODO (please comment if you have any thoughts on these!):

* [x] Is espconn still unsupported by lwip2? Don't know: just add note.
* [x] Windows .cmd install scripts are quite useable, just needs an `export.cmd` and documenting. We then don't need the custom sming choco scripts: we should remove those from documentation. Bit more than that: separate PR.
* [x] Is there a way to check/fix use of smart quotes automatically? Nope. I'll write one.
* [x] Add notes on debugging in vscode - already there, just not as involved as Eclipse
* [x] Is eclipse still a good development environment? I always found it slow, complicated and clunky, but maybe that's changed?  Is the documentation still correct for current versions?
* [x] Lots of duplication in eclipse debugging pages, merge this into single document

README.md

@@ -1,6 +1,6 @@
 # Sming
 
-Sming is an asynchronous embedded C/C++ framework with superb performance and multiple network features. 
+Sming is an asynchronous embedded C++ framework with superb performance and multiple network features.
 Sming is [open source](LICENSE), modular and supports [multiple architectures](https://sming.readthedocs.io/en/latest/features.html) including ESP8266, ESP32 and RP2040.
 
 [![Examples](https://github.com/SmingHub/Sming/wiki/images/small/combine.png)](https://github.com/SmingHub/Sming/wiki/examples)
@@ -42,20 +42,21 @@ The purpose of Sming is to simplify the creation of embedded applications. The d
 
 To follow the latest development you will need to clone our `develop` branch:
 
-```
+```bash
 git clone https://github.com/SmingHub/Sming.git
 ```
 
 
 ## Examples
-The examples are a great way to learn the API and brush up your C/C++ knowledge.
-Once you have completed the installation of the development tools, you can get the latest source code.
 
-```
+The examples are a great way to learn the API and brush up your C++ knowledge.
+Once you have completed the installation of the development tools, you can get the latest source code:
+
+```bash
 git clone https://github.com/SmingHub/Sming.git
 ```
 
-And check some of the examples.
+And check some of the examples:
 
 - [Basic Blink](#basic-blink)
 - [Simple GPIO input/output](#simple-gpio-inputoutput)
@@ -68,9 +69,10 @@ And check some of the examples.
 - [Email Client](#email-client)
 
 ### Basic Blink
+
 Blinking is something like the "Hello World" example for the embedded world. You can check it using the commands below:
 
-```
+```bash
 cd Sming/samples
 cd Basic_Blink
 make # -- compiles the application
@@ -80,6 +82,7 @@ make flash # -- tries to upload the application to your ESP8266 device.
 More information at **[Sample Projects](https://sming.readthedocs.io/en/latest/samples.html)** page.
 
 ### Simple GPIO Input/Output
+
 ```c++
 #define LED_PIN 2 // GPIO2
 ...
@@ -90,18 +93,21 @@ digitalWrite(LED_PIN, HIGH);
 For a complete example take a look at the [Basic_Blink](samples/Basic_Blink/app/application.cpp) sample.
 
 ### Start Serial Communication
+
 ```c++
 Serial.begin(9600);
 Serial.println("Hello Sming! Let's do smart things.");
 ```
 
 ### Connect to WiFi
+
 ```c++
 WifiStation.enable(true);
 WifiStation.config("LOCAL-NETWORK", "123456789087"); // Put your SSID and password here
 ```
 
 ### Read DHT22 sensor
+
 ```c++
 #include <Libraries/DHTesp/DHTesp.h> // This is just a popular Arduino library!
 
@@ -110,35 +116,37 @@ DHTesp dht;
 
 void init()
 {
-  dht.setup(DHT_PIN, DHTesp::DHT22);
+  dht.setup(DHT_PIN, DHTesp::DHT22);
 
-  float h = dht.getHumidity();
-  float t = dht.getTemperature();
+  float h = dht.getHumidity();
+  float t = dht.getTemperature();
 }
 ```
 
 Take a look at the code of the [Humidity_DHT22](samples/Humidity_DHT22/app/application.cpp) sample.
 
 ### HTTP Client
+
 ```c++
 HttpClient thingSpeak;
 ...
 thingSpeak.downloadString("http://api.thingspeak.com/update?key=XXXXXXX&field1=" + String(sensorValue), onDataSent);
 
 void onDataSent(HttpClient& client, bool successful)
 {
-  if (successful) {
-    Serial.println("Successful!");
-  }
-  else {
-    Serial.println("Failed");
-  }
+  if (successful) {
+    Serial.println("Successful!");
+  }
+  else {
+    Serial.println("Failed");
+  }
 }
 ```
 
 For more examples take a look at the [HttpClient](samples/HttpClient/app/application.cpp), [HttpClient_Instapush](samples/HttpClient_Instapush/app/application.cpp) and [HttpClient_ThingSpeak](samples/HttpClient_ThingSpeak/app/application.cpp) samples.
 
 ### OTA Application Update
+
 ```c++
 void doUpgrade()
 {
@@ -151,20 +159,21 @@ void doUpgrade()
   // select rom partition to flash
   auto part = ota.getNextBootPartition();
 
-  // The content located on ROM_0_URL will be stored to the new partition
-  otaUpdater->addItem(ROM_0_URL, part);
+  // The content located on ROM_0_URL will be stored to the new partition
+  otaUpdater->addItem(ROM_0_URL, part);
 
-  // and/or set a callback (called on failure or success without switching requested)
-  otaUpdater->setCallback(upgradeCallback);
+  // and/or set a callback (called on failure or success without switching requested)
+  otaUpdater->setCallback(upgradeCallback);
 
-  // start update
-  otaUpdater->start();
+  // start update
+  otaUpdater->start();
 }
 ```
 
 For a complete example take a look at the [Basic_Ota](samples/Basic_Ota/app/application.cpp) sample.
 
 ### HTTP Server
+
 ```c++
 server.listen(80);
 server.paths.set("/", onIndex);
@@ -178,28 +187,29 @@ Serial.println(WifiStation.getIP());
 
 void onIndex(HttpRequest &request, HttpResponse &response)
 {
-  TemplateFileStream *tmpl = new TemplateFileStream("index.html");
-  auto &vars = tmpl->variables();
-  vars["counter"] = String(counter);
-  vars["IP"] = WifiStation.getIP().toString();
-  vars["MAC"] = WifiStation.getMAC();
-  response.sendTemplate(tmpl);
+  TemplateFileStream *tmpl = new TemplateFileStream("index.html");
+  auto &vars = tmpl->variables();
+  vars["counter"] = String(counter);
+  vars["IP"] = WifiStation.getIP().toString();
+  vars["MAC"] = WifiStation.getMAC();
+  response.sendTemplate(tmpl);
 }
 
 void onFile(HttpRequest &request, HttpResponse &response)
 {
-  String file = request.getPath();
-  if (file[0] == '/')
-    file = file.substring(1);
+  String file = request.getPath();
+  if (file[0] == '/')
+    file = file.substring(1);
 
-  response.setCache(86400, true);
-  response.sendFile(file);
+  response.setCache(86400, true);
+  response.sendFile(file);
 }
 ```
 
 For more examples take a look at the [HttpServer_ConfigNetwork](samples/HttpServer_ConfigNetwork/app/application.cpp), [HttpServer_Bootstrap](samples/HttpServer_Bootstrap/app/application.cpp), [HttpServer_WebSockets](samples/HttpServer_WebSockets/app/application.cpp) and [HttpServer_AJAX](samples/HttpServer_AJAX/app/application.cpp) samples.
 
 ### Email Client
+
 ```c++
 SmtpClient emailClient;
 
@@ -221,34 +231,36 @@ emailClient.send(mail);
 
 int onMailSent(SmtpClient& client, int code, char* status)
 {
-    MailMessage* mail = client.getCurrentMessage();
+    MailMessage* mail = client.getCurrentMessage();
 
-    ...
+    ...
 
-    if(!client.countPending()) {
-        client.quit();
-    }
+    if(!client.countPending()) {
+        client.quit();
+    }
 
-    return 0;
+    return 0;
 }
 
 ```
 
 See the [SmtpClient sample](samples/SmtpClient/app/application.cpp) for details.
 
 ## Live Debugging
+
 Applications based on Sming Framework that are flashed and running on an ESP8266 device can be debugged using interactive debuggers.
 In order to debug an application it has to be re-compiled with the ENABLE_GDB=1 directive. And then flashed on the device. As shown below:
 
-```
+```bash
 cd $SMING_HOME/../samples/LiveDebug
 make clean
 make ENABLE_GDB=1
 make flashapp # <-- this will update only the application firmware.
 ```
 
 Once the debuggable application is flashed on the device the developers have to run GDB. The easiest way to run the command-line GDB is to execute the following command:
-```
+
+```bash
 make gdb
 ```
 
@@ -260,7 +272,8 @@ See [LiveDebug sample](samples/LiveDebug/) for details.
 
 ## Contribute
 
-You can contribute to Sming by
+You can contribute to Sming by:
+
 - Providing Pull Requests with new features, bug fixes, new ideas, etc. See [Contributing](https://smingdev.readthedocs.io/en/latest/contribute/index.html) for details.
 - Testing our latest source code and reporting issues.
 - Supporting us financially to acquire hardware for testing and implementing or out of gratitude
@@ -276,8 +289,10 @@ In addition to that anyone who is helping this project can file an expense. If t
 #### Backers and sponsors
 
 Thank you to all the people who have backed Sming
-<a href="https://opencollective.com/Sming#backers" target="_blank"><img src="https://opencollective.com/Sming/backers.svg?width=890"></a>
+<a href="https://opencollective.com/Sming#backers" target="_blank">
+<img src="https://opencollective.com/Sming/backers.svg?width=890" alt="backer"></a>
 
 or sponsored it.
 
-<a href="https://opencollective.com/Sming/sponsor/0/website" target="_blank"><img src="https://opencollective.com/Sming/sponsor/0/avatar.svg"></a>
+<a href="https://opencollective.com/Sming/sponsor/0/website" target="_blank">
+<img src="https://opencollective.com/Sming/sponsor/0/avatar.svg" alt="sponsor"></a>

Sming/Arch/Esp32/Components/driver/hw_timer.rst

@@ -3,25 +3,6 @@ hw_timer: Hardware Timers
 
 Driver for hardware timers.
 
-Variables
----------
-
-.. envvar:: USE_US_TIMER
-
-   0 (default): Use default /256 prescale for Timer2
-   1: Use /16 prescale
-
-   The following functions depend on Timer2:
-   - NOW() return value, the Timer2 tick count
-   - Software timers
-   - System time
-
-   Software timers are driven by Timer2, which by default uses a /256 prescale
-   providing a resolution of 3.2us and a range of 1' 54".
-
-   Enabling this setting increases the resolution to 200ns but reduces the maximum
-   software timer to 7" 9.5s.
-
 API Documentation
 -----------------
 

Sming/Arch/Esp32/Components/driver/i2s.rst

@@ -1,64 +1,4 @@
 I2S: Inter-IC Serial communications
 ===================================
 
-Introduction
-------------
-
-`I2S <https://en.wikipedia.org/wiki/I%C2%B2S>`__ was designed for transfer of digital audio data.
-
-The ESP8266 has two I2S modules (one transmitter and one receiver), both with hardware
-`DMA <https://en.wikipedia.org/wiki/Direct_memory_access>`__ support, which means transfers from
-RAM to the hardware SPI FIFO can be handled directly in hardware without any CPU involvement.
-
-
-Sming I2S support
------------------
-
-The Sming driver deals with the complicated of setting up the hardware, using an API
-similar to that in the Espressif RTOS SDK. In addition, DMA buffers may be accessed directly
-to avoid double-buffering and the associated RAM and copy overhead.
-
-
-Applications
-------------
-
-Audio
-~~~~~
-
-Playing MIDI files, MP3 files, speech synthesis, etc. is all possible using the ESP8266,
-though many audio applications require considerable processing power.
-That means you may need to disable WiFi and set the processor to run at full 160MHz speed.
-
-High-quality multi-channel audio requires an external I2S DAC, which is what the protocol
-was designed for in the first place. You may find problems with insufficient RAM,
-but you can always add external SPI RAM.
-
-More realistic uses include generating simple tones, beeps, playing pre-recorded WAV audio,
-etc. to supplement existing projects. This can all be done in the background without
-disrupting the system's main purpose, whatever that may be.
-
-For such applications you can generate single-channel audio via the I2S OUT pin,
-using `Pulse-density modulation <https://en.wikipedia.org/wiki/Pulse-density_modulation>`__.
-
-See the :library:`ToneGenerator` library for a demonstration of this.
-
-
-GPIO Expansion
-~~~~~~~~~~~~~~
-
-Expand GPIO using low-cost shift registers. https://github.com/lhartmann/esp8266_reprap.
-
-
-Pixel-strip control
-~~~~~~~~~~~~~~~~~~~
-
-Devices such as WS2812-based NeoPixels use a simple, single-wire protocol.
-I2S is ideal for this as it can be used to generate a precisely-timed bitstream
-with very low CPU loading.
-
-
-API Documentation
------------------
-
-.. doxygengroup:: i2s_driver
-   :content-only:
+Not currently implemented for Esp32.

Sming/Arch/Esp32/Components/gdbstub/README.rst

@@ -3,6 +3,4 @@ GDB Stub for Esp32
 
 This defines the command line to use when ``make gdb`` is run.
 
-Esp32 debugging is handled via JTAG interface.
-
-No additional code is required as serial debugging is not (currently) implemented.
+See :doc:`/debugging/esp32/index`.

Sming/Arch/Esp32/Components/heap/README.rst

@@ -1,12 +1,4 @@
-Heap
-====
+Esp32 Heap
+==========
 
-This Component implements heap-related housekeeping functions. Heap usage is tracked using :component:`malloc_count`.
-This also provides some validation (using *sentinels* to detect if memory blocks are overwritten).
-
-.. envvar:: ENABLE_MALLOC_COUNT
-
-   We require :component:`malloc_count` to keep track of heap usage for system_get_free_heap_size().
-   It does this by hooking the memory allocation routines (malloc, free, etc.).
-   If you wish to disable this behaviour, set `ENABLE_MALLOC_COUNT=0`.
-   If using tools such as `Valgrind <https://www.valgrind.org>`__, this will provide a cleaner trace.
+This Component supplements the actual heap implementation provided by the ESP IDF SDK.

Sming/Arch/Esp32/Components/sming-arch/README.rst

@@ -3,16 +3,3 @@ Sming (Esp32)
 
 This Component builds a library containing architecture-specific code, and defines dependencies for Sming to build for the Esp32.
 
-Interactive debugging on the device
------------------------------------
-
-.. envvar:: ENABLE_GDB
-
-   In order to be able to debug live directly on the ESP8266 microcontroller you
-   should re-compile your application with ``ENABLE_GDB=1`` directive.
-
-   undefined (default)
-      Compile normally
-   1
-      Compile with debugging support provided by :component-esp8266:`gdbstub`.
-      See also the :sample:`LiveDebug` sample.

Sming/Arch/Esp32/Components/spi_flash/README.rst

@@ -1,4 +1,4 @@
-Esp8266 SPI Flash Support
+Esp32 SPI Flash Support
 =========================
 
 Provides functions for access to flash memory.