Some more documentation fixes (#2864)

More documentation fixes. Two stragglers in source/arch and we can remove that directory. - Move esp-quick-toolchain info to esp8266 page and update. - arch/host/index is redundant, remove it Move arch-specific features off index page Fix broken GCC upgrade URLs - if compiler check fails direct to getting started page.
SmingHub · Jul 17, 2024 · ee230cf · ee230cf
1 parent 07f4472
commit ee230cf
Show file tree

Hide file tree

Showing 13 changed files with 66 additions and 79 deletions.
diff --git a/Sming/Arch/Esp8266/Components/libc/README.rst b/Sming/Arch/Esp8266/Components/libc/README.rst
@@ -4,4 +4,4 @@ Esp8266 LIBC Component
 .. highlight:: bash
 
 This Component supports integration of the standard C library provided by the compiler toolchain.
-See also :doc:`/arch/esp8266/getting-started/eqt`.
+See also :ref:`esp_quick_toolchain`.
diff --git a/Sming/Arch/Esp8266/README.rst b/Sming/Arch/Esp8266/README.rst
@@ -5,7 +5,7 @@ Support building Sming for the Esp8266 architecture.
 
 This is the SOC for which Sming was originally developed,
 so many of the low-level API calls reflect those in the
-`SDK </_inc/Sming/Arch/Esp8266/Components/esp8266/README>`.
+:doc:`SDK </_inc/Sming/Arch/Esp8266/Components/esp8266/README>`.
 These include functions such as
 :c:func:`system_get_free_heap_size`,
 :c:func:`system_update_cpu_freq`,
@@ -17,6 +17,20 @@ The Esp8266 is the device which popularised 32-bit microcontrollers
 with integrated WiFi capability, the so-called
 `System on a chip <https://en.wikipedia.org/wiki/System_on_a_chip>`__ (SoC).
 
+
+Features
+--------
+
+-  Integrated boot loader :component:`rboot` with support for 1MB ROMs, OTA firmware updating and ROM switching.
+-  :doc:`Crash handlers <debugging/index>` for analyzing/handling system restarts due to fatal errors or WDT resets.
+-  :component-esp8266:`PWM support <driver>` based on `Stefan Bruens PWM <https://github.com/StefanBruens/ESP8266_new_pwm.git>`__.
+-  Optional :component-esp8266:`custom heap allocation <heap>` based on `Umm Malloc <https://github.com/rhempel/umm_malloc.git>`__.
+-  Based on :component-esp8266:`Espressif NONOS SDK Version 3 <esp8266>`.
+
+
+Characteristics
+---------------
+
 Compared with more recent offerings such as the
 :doc:`ESP32 </_inc/Sming/Arch/Esp32/README>` and
 :doc:`RP2040 </_inc/Sming/Arch/Rp2040/README>`,
@@ -43,14 +57,44 @@ Weak hardware peripheral support
    hardware support for interfaces such as I2C and PWM is lacking and these must
    be implemented in software.
 
+.. _esp_quick_toolchain:
+
+ESP Quick Toolchain
+-------------------
+
+In Sming 4.0.1 support was added for the `ESP Quick Toolchain <https://github.com/earlephilhower/esp-quick-toolchain>`__.
+This is the required toolchain for compiling Sming for the Esp8266.
+
+At time of writing the current release is 
+`3.0.0-newlib4.0.0-gnu20 <https://github.com/earlephilhower/esp-quick-toolchain/releases/tag/3.0.0-newlib4.0.0-gnu20>`__
+for `GCC 10.2 <https://www.gnu.org/software/gcc/gcc-10>`__.
+
+The toolchain is consistent across development platforms which also use the
+standard C/C++ `NewLib <https://github.com/earlephilhower/newlib-xtensa>`__
+runtime libraries.
+
+
+Installation
+------------
+
+The easiest way to get started is with the Sming installer - see :doc:`/getting-started/index`.
+
+- Linux and MacOS: ``Tools/install.sh esp8266``.
+- Windows: ``Tools\install esp8266``.
+
 
 Configuration Variables
 -----------------------
 
 .. envvar:: ESP_HOME
 
    This contains the base directory for the toolchain used to build the framework.
-   See also :doc:`/arch/esp8266/getting-started/eqt`.
+   See :ref:`esp_quick_toolchain`.
+
+   The Sming installer extracts the toolchain to:
+
+   - ``/opt/esp-quick-toolchain`` for linux and MadOS
+   - ``C:\tools\esp-quick-toolchain`` for Windows
 
 
 Components

diff --git a/Sming/Arch/Esp8266/build.mk b/Sming/Arch/Esp8266/build.mk
@@ -33,8 +33,6 @@ OBJDUMP			 	:= $(TOOLSPEC)objdump
 NM				:= $(TOOLSPEC)nm
 GDB				:= $(TOOLSPEC)gdb
 
-GCC_UPGRADE_URL := https://sming.readthedocs.io/en/latest/arch/esp8266/getting-started/eqt.html
-
 CPPFLAGS += \
 	-nostdlib \
 	-mlongcalls \

diff --git a/Sming/Arch/Host/README.rst b/Sming/Arch/Host/README.rst
@@ -3,12 +3,18 @@ Sming Host Emulator
 
 .. highlight:: bash
 
+Sming allows most libraries and sample applications to be compiled on a Linux/MacOs/Windows
+development system and be tested before uploading them to the microcontroller.
+
+If you want to try it we have an
+`interactive tutorial <https://killercoda.com/slaff/scenario/sming-host-emulator>`__
+that can be run directly from your browser.
+
+For installation details see :doc:`/getting-started/index`.
+
 Summary
 -------
 
-Allows Sming applications to be built as an executable to run on the
-development host (Windows, Linux or MacOS).
-
 This is a source-level emulator for developing and testing new framework
 code prior to flashing a real device.
 

diff --git a/Sming/Arch/Host/build.mk b/Sming/Arch/Host/build.mk
@@ -40,8 +40,6 @@ endif
 
 GDB		:= $(TOOLSPEC)gdb
 
-GCC_UPGRADE_URL := https://sming.readthedocs.io/en/latest/arch/host/host-emulator.html\#c-c-32-bit-compiler-and-libraries
-
 BUILD_VARS += BUILD64
 ifeq ($(UNAME),Darwin)
 BUILD64 := 1

diff --git a/Sming/build.mk b/Sming/build.mk
@@ -290,7 +290,7 @@ DEBUG_VARS			+= SMING_C_STD
 SMING_C_STD			?= c11
 CFLAGS				+= -std=$(SMING_C_STD)
 
-# Select C++17 if supported, defaulting to C++11 otherwise
+# C++17 is minimum required standard
 DEBUG_VARS			+= SMING_CXX_STD
 SMING_CXX_STD		?= c++17
 CXXFLAGS			+= -std=$(SMING_CXX_STD)
@@ -299,10 +299,9 @@ COMPILER_VERSION_MAJOR := $(firstword $(subst ., ,$(COMPILER_VERSION)))
 COMPILER_VERSION_COMPATIBLE := $(shell expr $(COMPILER_VERSION_MAJOR) \>= $(COMPILER_VERSION_MIN))
 
 ifeq ($(COMPILER_VERSION_COMPATIBLE),0)
-ifneq ($(GCC_UPGRADE_URL),)
-$(info Instructions for upgrading your compiler can be found here: $(GCC_UPGRADE_URL))
-endif
-$(error Please upgrade your compiler to $(COMPILER_NAME) $(COMPILER_VERSION_MIN) or newer)
+$(info Please upgrade your compiler to $(COMPILER_NAME) $(COMPILER_VERSION_MIN) or newer)
+$(info See https://sming.readthedocs.io/en/latest/getting-started/index.html)
+$(error .)
 endif
 endif
 

diff --git a/Sming/building.rst b/Sming/building.rst
@@ -75,8 +75,8 @@ These are the main variables you need to be aware of:
 
    The build standard applied for the framework.
 
-   This defaults to C++17 if the toolchain supports it (GCC 5+), C++11 otherwise.
-   You can override to use other standards, such as ``c++2a`` for experimental C++20 support.
+   C++17 is the minimum required standard.
+   You can override to use other standards, such as ``c++20``.
 
 
 These variables are available for application use:

diff --git a/docs/source/about.rst b/docs/source/about.rst
@@ -8,7 +8,7 @@ Sming is an open-source asynchronous C++ embedded framework with networking supp
 and is designed to be reliable, responsive and modular.
 
 The project was started in 2015 for the Esp8266 and has since been adapted to other devices,
-including a :doc:`host emulator <arch/host/index>` for advanced development and debugging.
+including a :doc:`host emulator </_inc/Sming/Arch/Host/README>` for advanced development and debugging.
 
 The framework is actively developed and has an extensive suite of integration tests.
 

diff --git a/docs/source/arch/esp8266/getting-started/eqt.rst b/docs/source/arch/esp8266/getting-started/eqt.rst
diff --git a/docs/source/arch/host/index.rst b/docs/source/arch/host/index.rst
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -22,7 +22,7 @@ Summary
 -------
 -  Superb performance and memory usage: Sming compiles to native firmware!
 -  Fast and user-friendly C++ development
--  Integrated :doc:`host emulator <arch/host/index>` to assist with developing, testing and debugging
+-  Integrated :doc:`host emulator </_inc/Sming/Arch/Host/README>` to assist with developing, testing and debugging
    libraries and applications on a PC. It even includes networking support!
    Try it out online `here <https://killercoda.com/slaff/scenario/sming-host-emulator>`__.
 -  Built-in powerful wireless modules
@@ -65,18 +65,6 @@ Summary
    -  :library:`GoogleCast` library allows control of ChromeCast devices or smart TVs supporting the GoogleCast protocol.
    -  :library:`HueEmulator` provides simple way to implement devices compatible with Amazon Alexa.
 
--  ESP8266 features
-
-   -  Integrated boot loader :component:`rboot` with support for 1MB ROMs, OTA firmware updating and ROM switching.
-   -  :doc:`Crash handlers <debugging/index>` for analyzing/handling system restarts due to fatal errors or WDT resets.
-   -  :component-esp8266:`PWM support <driver>` based on `Stefan Bruens PWM <https://github.com/StefanBruens/ESP8266_new_pwm.git>`__.
-   -  Optional :component-esp8266:`custom heap allocation <heap>` based on `Umm Malloc <https://github.com/rhempel/umm_malloc.git>`__.
-   -  Based on :component-esp8266:`Espressif NONOS SDK Version 3 <esp8266>`.
-
--  ESP32 features
-
-   - Based on :component-esp32:`ESP IDF SDK <esp32>`
-
 
 .. toctree::
    :caption: Contents:

diff --git a/docs/source/information/develop/components.rst b/docs/source/information/develop/components.rst
@@ -84,7 +84,7 @@ Supported architectures
 
 Unless there are specific reasons not to do so, Components should work on all
 supported architectures. In particular, it should build and run under the
-:doc:`Host Emulator </arch/host/index>`.
+:doc:`Host Emulator </_inc/Sming/Arch/Host/README>`.
 
 In order to do this, you should remove any low-level code from the library by:
 

diff --git a/docs/source/upgrading/4.4-4.5.rst b/docs/source/upgrading/4.4-4.5.rst
@@ -27,7 +27,7 @@ For more information read the updated :doc:`/tools/eclipse`.
 Esp8266 toolchain
 -----------------
 
-Sming now requires the :doc:`/arch/esp8266/getting-started/eqt` for building.
+Sming now requires the :ref:`esp_quick_toolchain` for building.
 
 Support for the old legacy toolchains (ESP open SDK, UDK) have been dropped.
 They may still work but are no longer tested.