Merge pull request #4 from slaff/fix/minor-docs-fixes

Minor changes to the content.

docs/README.md

@@ -1,7 +1,7 @@
 # Sming Documentation
 
 This directory contains the build system for Sming's documentation.
-It is intended to be read online via (Read The Docs)[https://sming.readthedocs.io].
+It is intended to be read online via [Read The Docs](https://sming.readthedocs.io).
 
 The `source` directory contains some top-level files however most of the
 information is obtained from the various README files associated with the source code.
@@ -14,12 +14,12 @@ Should already be available as part of Sming build system
 
 ### doxygen
 
-See http://www.doxygen.nl/
+See [http://www.doxygen.nl/](http://www.doxygen.nl/)
 
 For Linux:
 
 	sudo apt install doxygen
-	
+
 ### Python 3 + Sphinx
 
 For Linux, run `sudo apt install python3-sphinx python3-pip python3-setuptools`.

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

@@ -1,20 +1,8 @@
 Getting Started: ESP8266
 ========================
 
-Development System Installation
--------------------------------
-
 .. toctree::
    :glob:
    :maxdepth: 1
 
    *
-
-
-Compilation and flashing
-------------------------
-
-You can find more information about compilation and flashing process by
-reading esp8266.com forum discussion thread. Official ESP8266
-documentation can be found in the `Espressif
-website <https://espressif.com/en/support/download/documents?keys=&field_type_tid%5B%5D=14>`__.

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

@@ -10,16 +10,16 @@ If you want to try it we have an
 that can be run directly from your browser.
 
 Requirements (Linux)
-====================
+-------------------------
 
 Modern Linux distribution
--------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Most popular modern distributions should be fine. At the moment we
 develop only with Ubuntu 16.04 and 18.04.
 
 C/C++ 32 bit compiler and libraries
------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If your OS is 64 bit then you should install also 32 bit C/C++ compiler
 and libraries. Under Ubuntu those can be installed using the command
@@ -30,7 +30,7 @@ below
    sudo apt-get install gcc-multilib g++-multilib
 
 CMake 3.8 or newer
-------------------
+~~~~~~~~~~~~~~~~~~
 
 For the compilation of LWIP ``CMake`` version 3.8 or newer is required.
 In order to get newer Cmake version under Ubuntu 16.04 one should
@@ -46,7 +46,7 @@ execute the commands below:
    sudo ln -s /opt/cmake/bin/cmake /usr/bin/cmake
 
 Requirements (Windows)
-======================
+----------------------
 
 For Windows, make sure your `MinGW` distro is up to date. If you run
 `gcc --version` you should get `gcc (MinGW.org GCC-6.3.0-1) 6.3.0` or
@@ -61,10 +61,10 @@ later. If it's older, execute these commands:
    If you don't already have MinGW installed, see :doc:`arch/esp8266/getting-started/windows` for the Esp8266.
 
 Compilation
-===========
+-----------
 
 Environment variables
----------------------
+~~~~~~~~~~~~~~~~~~~~~
 
 :envvar:`SMING_ARCH` must be set to use ``Host`` as the desired architecture:
 
@@ -73,7 +73,7 @@ Environment variables
    export SMING_ARCH=Host
 
 Debug Build
------------
+~~~~~~~~~~~
 
 If you plan to use a debugger make sure to set :envvar:`ENABLE_GDB` and (optionally)
 :envvar:`ENABLE_LWIPDEBUG` before compiling the code:
@@ -84,7 +84,7 @@ If you plan to use a debugger make sure to set :envvar:`ENABLE_GDB` and (optiona
    export ENABLE_LWIPDEBUG=1  # <!-- this will compile also LWIP with debug symbols
 
 Initial Clean-up
-----------------
+~~~~~~~~~~~~~~~~
 
 Make sure that you are working on a clean source code tree. The
 following commands may help:
@@ -95,7 +95,7 @@ following commands may help:
    make dist-clean
 
 Sample compilation
-------------------
+~~~~~~~~~~~~~~~~~~
 
 Compile a sample as usual using the following command sequence:
 
@@ -105,7 +105,7 @@ Compile a sample as usual using the following command sequence:
    make
 
 Adapting existing code
-----------------------
+~~~~~~~~~~~~~~~~~~~~~~
 
 You may need to modify your existing applications to work with the
 emulator. Architecture-specific code should be moved into separate code
@@ -114,7 +114,7 @@ compiled using ``#ifdef ARCH_ESP8266``. Similarly, you can check if the
 code is compiled for the emulator using ``#ifdef ARCH_HOST``.
 
 Running on the host
-===================
+-------------------
 
 Once the sample is compiled you can run it on the host using the command
 below:
@@ -132,7 +132,7 @@ If you would like to run the code only then use the following command:
    make run
 
 Networking
-----------
+~~~~~~~~~~
 
 Support is provided via TAP network interface (a virtual network layer
 operating at the ethernet frame level). A TAP interface must be created
@@ -162,16 +162,16 @@ select the first ``tap`` interface found. To override this, use the
 ``--ifname`` option.
 
 Troubleshooting
-===============
+---------------
 
 Issue 1: fatal error: sys/cdefs.h: No such file or directory
-------------------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Make sure to install the 32bit version of the GNU C and C++ compiler,
 development package and libraries.
 
 Issue 2: fatal error: bits/c++config.h: No such file or directory
------------------------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Make sure to install the 32bit version of the GNU C and C++ compiler,
 development package and libraries.

docs/source/getting-started.rst

@@ -9,6 +9,7 @@ Sming supports multiple architectures. Choose the architecture of your choice to
 .. toctree::
    :glob:
    :titlesonly:
+   :maxdepth: 1
 
    /arch/esp8266/getting-started/index
    /arch/host/host-emulator

docs/source/index.rst

@@ -17,7 +17,6 @@ It supports multiple architectures as ESP8266 for example.
 
 Summary
 -------
-
 -  Superb performance and memory usage (Sming compiles to native firmware!)
 -  Fast and user friendly development
 -  Simple yet powerful hardware API wrappers
@@ -26,32 +25,24 @@ Summary
 -  Built-in powerful wireless modules
 -  Powerful asynchronous (async) network stack.
 
-   -  Async TCP and UDP stack based on `LWIP <http://savannah.nongnu.org/projects/lwip/>`__
-
-   -  With clients supporting: HTTP, MQTT, WebSockets and SMTP
-
-   -  And servers for: DNS, FTP, HTTP(+ WebSockets), Telnet
-
-   -  With SSL support for all network clients and servers based on
-      `axTLS 2.1+ <https://github.com/igrr/axtls-8266>`__ with
-      `Lwirax <https://github.com/attachix/lwirax/>`__.
-
-   -  Out of the box support for OTA over HTTPS.
+  -  Async TCP and UDP stack based on `LWIP <http://savannah.nongnu.org/projects/lwip/>`__
+  -  With clients supporting: HTTP, MQTT, WebSockets and SMTP
+  -  And servers for: DNS, FTP, HTTP(+ WebSockets), Telnet
+  -  With SSL support for all network clients and servers based on `axTLS 2.1+ <https://github.com/igrr/axtls-8266>`__ with `Lwirax <https://github.com/attachix/lwirax/>`__.
+  -  Out of the box support for OTA over HTTPS.
 
 -  ESP8266 specific features
 
-   -  Integrated boot loader :component-esp8266:`rboot`
-      with support for 1MB ROMs, OTA firmware updating and ROM switching
-   -  :doc:`Crash handlers <information/debugging>` for analyzing/handling system restarts due to fatal errors or WDT resets.
-   -  :component-esp8266:`PWM support <pwm_open>` based on `Stefan Bruens PWM <https://github.com/StefanBruens/ESP8266_new_pwm.git>`__
-   -  Optional :component-esp8266:`custom heap allocation <custom_heap>` based on `Umm Malloc <https://github.com/rhempel/umm_malloc.git>`__
-   -  Based on :component-esp8266:`Espressif NONOS SDK <esp8266>`. Tested with versions 1.5, 2.0 and 3.0.
+  -  Integrated boot loader :component-esp8266:`rboot` with support for 1MB ROMs, OTA firmware updating and ROM switching
+  -  :doc:`Crash handlers <information/debugging>` for analyzing/handling system restarts due to fatal errors or WDT resets.
+  -  :component-esp8266:`PWM support <pwm_open>` based on `Stefan Bruens PWM <https://github.com/StefanBruens/ESP8266_new_pwm.git>`__
+  -  Optional :component-esp8266:`custom heap allocation <custom_heap>` based on `Umm Malloc <https://github.com/rhempel/umm_malloc.git>`__
+  -  Based on :component-esp8266:`Espressif NONOS SDK <esp8266>`. Tested with versions 1.5, 2.0 and 3.0.
 
 -  Linux/Windows features
 
-   -  Sming has a :doc:`host emulator <arch/host/host-emulator>` that allows libraries and sample applications to be compiled on a Linux/Windows host system
-      and be tested before uploading them to an actual microcontroller.
-
+  -  Sming has a :doc:`host emulator <arch/host/host-emulator>` that allows libraries and sample applications to be compiled on a Linux/Windows host system
+     and be tested before uploading them to an actual microcontroller.
 
 .. toctree::
    :caption: Contents: