Sort 'getting-started' documentation by platform, in sub-directories

docs/source/arch/esp32/getting-started/index.rst

@@ -4,29 +4,58 @@ Getting Started: Esp32
 Requirements
 ------------
 
-In order to be able to compile for the ESP32 architecture you should have ESP-IDF v4.1 installed.
+Pre-requisites::
 
-Get the latest `release/v4.1` branch. This can be done using the following command::
+   sudo apt-get install ninja-build ccache
 
-    git clone -b release/v4.1 https://github.com/espressif/esp-idf.git
+The ESP-IDF v4.1 and corresponding toolchains are requied to build for the ESP32 architecture.
 
-Note that a recursive clone is not required as the necessary submodules will be fetched during the build stage.
+Linux:
 
-Now install the toolchain::
+.. code-block:: bash
 
-   esp-idf/install
+   source $(SMING_HOME)/Arch/Esp32/Tools/install.sh
 
-For information about pre-requisites and other issues, see
+   export IDF_PATH=/opt/esp-idf
+   export IDF_TOOLS_PATH=/opt/esp32
+   export ESP32_PYTHON_PATH=/usr/bin
+   git clone -b release/v4.1 https://github.com/espressif/esp-idf.git /opt/esp-idf
+   mkdir -p $IDF_TOOLS_PATH
+   SMINGTOOLS=https://github.com/SmingHub/SmingTools/releases/download/1.0
+   ESPTOOLS=esp32-tools-linux-4.1.zip
+   wget $SMINGTOOLS/$ESPTOOLS
+   unzip $ESPTOOLS -d $IDF_TOOLS_PATH/dist
+   python3 $IDF_PATH/tools/idf_tools.py install
+   python3 -m pip install -r $IDF_PATH/requirements.txt
+
+
+Windows:
+
+.. code-block:: batch
+
+   set IDF_PATH=c:\tools\esp-idf
+   set IDF_TOOLS_PATH=c:\tools\esp32
+   set ESP32_PYTHON_PATH=c:\Python39
+   git clone -b release/v4.1 https://github.com/espressif/esp-idf.git %IDF_PATH%
+   mkdir %IDF_TOOLS_PATH%
+   SMINGTOOLS=https://github.com/SmingHub/SmingTools/releases/download/1.0
+   ESPTOOLS=esp32-tools-windows-4.1.7z
+   curl -LO %SMINGTOOLS%/%ESPTOOLS%
+   7z -o%IDF_TOOLS_PATH%\dist x %ESPTOOLS%
+   python3 %IDF_PATH%\tools\idf_tools.py install
+   python3 -m pip install -r %IDF_PATH%\requirements.txt
+
+
+For further information about installation and other issues, see
 `ESP-IDF documentation <https://docs.espressif.com/projects/esp-idf/en/v4.1/get-started/index.html#installation-step-by-step>`__.
 
+
 Building
 --------
 
 Make sure that the IDF_PATH environmental variable is set. On Linux you can use for example the following command::
 
-    export IDF_PATH=path/to/esp-idf
-
-Replace `path/to` with the correct path.
+    export IDF_PATH=/opt/esp-idf
 
 Note that you do not need to run ``IDF export.sh`` as this is handled by the Sming build system.
 This simplifies use within the Eclipse IDE as there is only one environment variable to set.

docs/source/arch/esp8266/getting-started/index.rst

@@ -21,10 +21,5 @@ Contents
    :glob:
    :maxdepth: 1
 
-   linux
-   macos
-   windows
    windows-manual
-   docker
    eqt
-   config

docs/source/arch/host/host-emulator.rst

@@ -27,7 +27,6 @@ The latest versions of Sming require GCC version 8 or newer.
 If your OS is 64 bit then you should install also 32 bit C/C++ compiler and libraries.
 Here's a summary of how to do this::
 
-   sudo add-apt-repository ppa:ubuntu-toolchain-r/test
    sudo apt update
    sudo apt install gcc-9 g++-9
 
@@ -131,7 +130,7 @@ first, and requires root privilege. You can use the
 
    sudo ip tuntap add dev tap0 mode tap user `whoami`
    sudo ip a a dev tap0 192.168.13.1/24
-   sudo ifconfig tap0 up
+   sudo ip link set tap0 up
 
    # The following lines are needed if you plan to access Internet
    sudo sysctl net.ipv4.ip_forward=1
@@ -148,6 +147,10 @@ This creates the ``tap0`` interface. The emulator will automatically
 select the first ``tap`` interface found. To override this, use the
 ``--ifname`` option.
 
+You can list available network interfaces thus::
+
+   ip link
+
 Troubleshooting
 ---------------
 

docs/source/arch/esp8266/getting-started/config.rst → docs/source/getting-started/config.rst

@@ -1,5 +1,5 @@
-Configuring your Esp8266 device
--------------------------------
+Configuring your device
+-----------------------
 
 .. highlight:: bash
 
@@ -12,15 +12,16 @@ You can set these initially on the command line, like this::
 
    make SMING_ARCH=Esp8266 COM_PORT=/dev/ttyUSB3 COM_SPEED_ESPTOOL=921600
 
-For Windows expect to use COM2, COM3, etc.
+(For Windows or :doc:`windows/wsl` expect to use COM2, COM3, etc.)
 
-You can list the current set of configuration variables like this::
+Once you're happy with the settings, you can add them to your project's ``component.mk`` file.
+You may need to do this to reset the cached values::
 
-   make list-config
+   make config-clean
 
-If you want to reset back to default values, do this::
+The current set of configuration variables can be seen thus::
 
-   make config-clean
+   make list-config
 
 Other hardware-specific settings are stored in the hardware configuration file.
 You can examine the current configuration like this::

docs/source/arch/esp8266/getting-started/docker.rst → docs/source/getting-started/docker/index.rst

@@ -1,11 +1,14 @@
-*******************
-Docker Installation
-*******************
+******
+Docker
+******
+
+Docker is a useful tool if you want to experiment with Sming in an isolated environment.
 
-Docker is a useful option if you want to experiment with Sming in an isolated environment.
 If you're unfamiliar with Docker, you can find a good overview in the article,
 `What is a Container? <https://www.docker.com/resources/what-container>`__.
 
+This page shows how to create docker containers with all the necessary tools to
+build Sming applications.
 
 Install Docker
 ==============
@@ -21,43 +24,55 @@ Docker Compose makes dealing with the orchestration processes of Docker
 containers (such as starting up, shutting down, and setting up
 intra-container linking and volumes) really easy.
 
-With docker compose we can define the entire multi-container application
-in single file and then the application can be spinned up using one
-command.
+With *docker compose* we can define the entire multi-container application
+in a single file and spin it up using one command.
 
 Visit the official
 `Docker Compose Installation Page <https://docs.docker.com/compose/install/>`__
 and follow the instructions tailored for your operating system.
 
+Building images
+===============
+
+You can find the related Docker scripts in ``$SMING_HOME/Tools/Docker``.
+
+To build your own images, do this::
+
+   cd $SMING_HOME/Tools/Docker/cli
+   docker-compose build
+   cd $SMING_HOME/Tools/Docker/ide
+   docker-compose build
+
+
 Adjust your settings
 ====================
 
 ::
 
    sming-ide:
 
-    build: .
-    
-    volumes:
-      - ../../Sming/:/opt/sming/
-      
+     build: .
+
+     volumes:
+       - ../../Sming/:/opt/sming/
+
     ports:
     #choose a free port to connect to the web C9 editor
     - "10080:80"
-    
+
     devices:
-     # uncomment to map your serial USB adaptor 
-     #- "/dev/ttyUSB0:/dev/ttyUSB0"
+      # uncomment to map your serial USB adaptor 
+      #- "/dev/ttyUSB0:/dev/ttyUSB0"
 
-    
     privileged: true
 
+
 Start your container
 ====================
 
 .. code-block:: bash
 
-   cd /opt/sming/docker/ && docker-compose -f sming-ide.yml up -d
+   cd /opt/sming/Tools/Docker/ide && docker-compose up -d
 
 Open your browser
 =================

docs/source/getting-started.rst → docs/source/getting-started/index.rst

@@ -5,23 +5,21 @@ Getting Started
 
 Development System Installation
 -------------------------------
-Sming supports multiple architectures. Choose the architecture of your choice to install the needed development software and toolchain(s).
 
+Choose your preferred development environment for how to install the needed development software and toolchain(s):
 
 .. toctree::
    :titlesonly:
    :maxdepth: 1
 
-   /arch/esp8266/getting-started/index
-   /arch/esp32/getting-started/index
-   /arch/host/host-emulator
+   linux/index
+   macos/index
+   windows/index
+   docker/index
 
 You can also try Sming without installing anything locally.
 We have an  `interactive tutorial <https://www.katacoda.com/slaff/scenarios/sming-host-emulator>`__ that can be run directly from your browser.
 
-Windows users may also wish to consider building in a Linux virtual environment.
-See :doc:`Windows WSL <windows-wsl>` for further details.
-
 
 Documentation
 -------------
@@ -35,13 +33,6 @@ 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.
-
-::
-
-   git clone https://github.com/SmingHub/Sming.git
-
-And check some of the examples.
 
 -  `Basic Blink <#basic-blink>`__
 -  `Simple GPIO input/output <#simple-gpio-inputoutput>`__