documentation: work on quickstart, add tabs sphinx extension

Documentation/Pipfile

@@ -9,6 +9,7 @@ verify_ssl = true
 m2r2 = "*"
 sphinx_rtd_theme = "*"
 Sphinx = "*"
+sphinx-tabs = "*"
 
 [requires]
 python_version = "3"

Documentation/_static/custom.css

@@ -58,3 +58,23 @@ table.valign-top td {
   vertical-align: top !important;
 }
 
+/* Make <kbd> elements look nice */
+
+kbd {
+  margin: 0px 0.1em;
+  padding: 0.1em 0.6em;
+  border-radius: 3px;
+  border: 1px solid rgb(204, 204, 204);
+  color: rgb(51, 51, 51);
+  line-height: 1.4;
+  font-family: Arial,Helvetica,sans-serif;
+  font-size: 10px;
+  display: inline-block;
+  box-shadow: 0px 1px 0px rgba(0,0,0,0.2), inset 0px 0px 0px 2px #ffffff;
+  background-color: rgb(247, 247, 247);
+  -moz-box-shadow: 0 1px 0px rgba(0, 0, 0, 0.2), 0 0 0 2px #ffffff inset;
+  -webkit-box-shadow: 0 1px 0px rgba(0, 0, 0, 0.2), 0 0 0 2px #ffffff inset;
+  -moz-border-radius: 3px;
+  -webkit-border-radius: 3px;
+  text-shadow: 0 1px 0 #fff;
+}

Documentation/conf.py

@@ -53,6 +53,7 @@
     "m2r2",
     'sphinx.ext.autosectionlabel',
     'sphinx.ext.todo',
+    'sphinx_tabs.tabs'
 ]
 
 source_suffix = [ '.rst', '.md' ]

Documentation/contributing/documentation.rst

@@ -145,6 +145,25 @@ In case you need to leave a TODO note in the documentation to point that somethi
 which is available via the ``sphinx.ext.todo`` extension. This will let the reader of the documentation also know that the documentation
 is not yet finished somewhere and may further motivate a contribution.
 
+User Indications
+----------------
+
+To indicate a keypress, menu action or GUI button selection, use the following:
+
+.. code-block:: RST
+
+  Go into menu :menuselection:`File --> Save As`, click :guilabel:`&OK` or press :kbd:`Enter`.
+
+which would render as:
+
+Go into menu :menuselection:`File --> Save As`, click :guilabel:`&OK` or press :kbd:`Enter`.
+
+Tabbed examples
+---------------
+
+To indicate different instructions/examples for different scenarios (for example, different Operating
+Systems) use the `tabs <https://github.com/executablebooks/sphinx-tabs>`_ extension (see link for examples).
+
 Tips
 ====
 

Documentation/quickstart/compiling.rst

@@ -1,57 +1,82 @@
 .. include:: /substitutions.rst
 .. _compiling:
 
+=========
 Compiling
 =========
 
-Now that we've installed Apache NuttX prerequisites and downloaded the source code, we are ready to compile the source code
-into an executable binary file that can be run on the embedded board.
+Now that we've installed Apache NuttX prerequisites and downloaded the source code,
+we are ready to compile the source code into an executable binary file that can
+be run on the embedded board.
 
-#. List Possible Apache NuttX Base Configurations
+Initialize Configuration
+========================
 
-   Find your hardware and a good starting application in the list of base configurations. In the application list,
-   ``nsh`` is the Apache NuttX Shell, an interactive commandline that's a good starting place if you're new.
+The first step is to initialize NuttX configuration for a given board, based from
+a pre-existing configuration. To list all supported configurations you can do:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
        $ ./tools/configure.sh -L | less
+       
+The output is in the format ``<board name>:<board configuration>``. You will see that
+generally all boards support the ``nsh`` configuration which is a good sarting point
+since it enables booting into the interactive command line
+:doc:`/components/nsh/index`.
 
-#. Initialize Configuration
-
-   Pick one of the board:application base configuration pairs from the list, and feed it to the
-   configuration script. The ``-l`` tells use that we're on Linux. macOS and Windows builds are
-   possible, this guide doesn't cover them yet.
+To choose a configuration you pass the ``<board name>:<board configuration>`` option
+to ``configure.sh`` and indicate your host platform, such as:
 
-    .. code-block:: bash
+    .. code-block:: console
 
        $ cd nuttx
-       $ # this is the basic layout of the command:
-       $ # ./tools/configure.sh -l <board-name>:<config-dir>
-       $ # for example:
-       $ ./tools/configure.sh -l sama5d2-xult:nsh
+       $ ./tools/configure.sh -l stm32f4discovery:nsh
+       
+The ``-l`` tells use that we're on Linux (macOS and Windows builds are
+possible). Use the ``-h`` argument to see all available options.
+
+Customize Your Configuration (Optional)
+=======================================
 
-#. Customize Your Configuration (Optional)
+This step is optional. Right now, this is mainly to get familiar with how it
+works– you don't need to change any of the options now, but knowing how
+to do this will come in handy later.
 
-   This step is optional. Right now, this is mainly to get familiar with how it works– you don't need to change
-   any of the options now, but knowing how to do this will come in handy later.
+There are a lot of options. We'll cover a few of them here.
+Don't worry about the complexity– you don't have to use most of the options.
 
-   There are a lot of options. We'll cover a few of them here. Don't worry about the complexity– you don't have to use most of the options.
+.. code-block:: console
 
-    .. code-block:: bash
+   $ cd nuttx/
+   $ make menuconfig
+   
+.. todo::
+  Explain some useful options.
 
-       $ make menuconfig
+Build NuttX
+===========
 
-#. Compile NuttX
+We can now build NuttX. To do so, you can simply run:
 
-    .. code-block:: bash
+  .. code-block:: console
 
-       $ make clean; make
+     $ cd nuttx/
+     $ make make
+     
+The build will complete by generating the binary outputs
+inside `nuttx` directory. Typically this includes the `nuttx`
+ELF file (suitable for debugging using `gdb`) and a `nuttx.bin`
+file that can be flashed to the board.     
+
+To clean the build, you can do:
 
-#. Install the Executable Program on Your Board
+  .. code-block:: console
 
-   This step is a bit more complicated, depending on your board. It's covered in the section
-   :ref:`Running Apache NuttX <running>`.
+     $ make clean
+     
+It is recommended that after manually modifying the configuration you first clean
+before building.
 
 ----