fix bugs in quickstart docs

- change Gnu to GNU
- fix formatting and link fixes
- add menuconfig screenshot
- replaced config file edits with kconfig-tweak
- fix section numbering
- removed leftover todo in quickstart/index.rst
- rewrote debugging section to use menuconfig

Documentation/guides/drivers.rst

@@ -80,7 +80,7 @@ modification.
       * stack frame printf
       * thread printf
 
-    * `GDB — the Gnu Debugger <https://www.gnu.org/software/gdb/>`_
+    * `GDB — the GNU Debugger <https://www.gnu.org/software/gdb/>`_
 
       GDB is a great tool. In this guide we've already used it to load our program and run it. But it can do a lot
       more. You can single-step through code, examine variables and memory, set breakpoints, and more. I generally use

Documentation/quickstart/build_and_make.rst

@@ -19,9 +19,9 @@ The ``$(TOPDIR)`` directory holds:
 
 That directory also holds:
 
--  The makefile fragment ```.config`` <#boardconfigsubdirs>`__
+-  The makefile fragment :ref:`.config <nuttx_boards>`
    that describes the current configuration, and
--  The makefile fragment ```Make.defs`` <#boardconfigsubdirs>`__
+-  The makefile fragment :ref:`Make.defs <nuttx_boards>`
    that provides customized build targets.
 
 Environment Variables
@@ -31,8 +31,7 @@ The specific environmental definitions
 are unique for each board but should include, as a minimum,
 updates to the ``PATH`` variable to include the full path to the
 architecture-specific toolchain identified in
-```Make.defs`` <#boardconfigsubdirs>`__.
+:ref:`Make.defs <nuttx_boards>`.
-
 
 First Time Make
 ---------------

Documentation/quickstart/configuring.rst

@@ -70,7 +70,7 @@ has your configuration options selected.
 
    Here's what you should see:
 
-   .. image:: ../images/menuconfig.png
+   .. image:: ../_static/images/menuconfig.png
        :width: 800px
        :align: center
        :alt: Screenshot of menuconfig system main screen
@@ -88,8 +88,6 @@ has your configuration options selected.
    Now let's save. Use the right and left arrow keys to select the ``Exit`` menu item at the
    bottom of the screen. Hit ``<return>`` to select it, hit ``<return>`` again, and again, finally
    hitting ``<return>`` in the ``Save Configuration`` dialog box.
-   |br|
-   |br|
 
 #. Make the New Configuration
 

Documentation/quickstart/debugging.rst

@@ -6,38 +6,49 @@ Debugging
 
 Finding and fixing bugs is an important part of the hardware and software development process. Sometimes you also need
 to use debugging techniques to understand how the system works. Two tools that are helpful are debug logging and
-debugging using the Gnu Debugger (gdb).
+debugging using the GNU Debugger (gdb).
 
 Debug Logging
 -------------
 
-NuttX has a powerful logging facility with ``info``, ``warn``, and ``error`` levels. You can enable debugging for your
+NuttX has a powerful system logging facility (syslog) with ``info``, ``warn``, and ``error`` levels. You can enable
-build for the ``net`` feature (TCP/IP stack) by putting the following lines in your ``.config`` file:
+debugging for your build for the subsystem or feature by using the ``menuconfig`` system.
 
-    ::
+.. code-block:: console
 
-       CONFIG_DEBUG_ALERT=y
+   $ make menuconfig
-       CONFIG_DEBUG_FEATURES=y
-       CONFIG_DEBUG_ERROR=y
-       CONFIG_DEBUG_WARN=y
-       CONFIG_DEBUG_INFO=y
-       CONFIG_DEBUG_ASSERTIONS=y
-       CONFIG_DEBUG_NET=y
-       CONFIG_DEBUG_NET_ERROR=y
-       CONFIG_DEBUG_NET_WARN=y
-       CONFIG_DEBUG_NET_INFO=y
-       CONFIG_DEBUG_SYMBOLS=y
-       CONFIG_DEBUG_NOOPT=y
-       CONFIG_SYSLOG_TIMESTAMP=y
 
-Note that turning all these to ``y`` will produce an incredible amount of logging output. Set the level you want and
+The debug options are available under ``Build Setup`` > ``Debug Options``. You will most likely have to enable the
-the area you're interested in to ``y``, and the rest to ``n``, and then recompile. You can see the full list of
+following options:
-debug feature areas in the file `debug.h <https://github.com/apache/incubator-nuttx/blob/master/include/debug.h>`__.
 
-Timestamps can be enabled by setting ``CONFIG_SYSLOG_TIMESTAMP=y``.
+* ``Enable Debug Features`` — selecting this will turn on subsystem-level debugging options, they will become visible
+  on the page below. You can then select the ones you want.
+* ``Enable Error Output`` — this will only log errors.
+* ``Enable Warnings Output`` — this will log warnings and errors.
+* ``Enable Informational Debug Output`` — this will produce informational output, warnings, and errors.
+
+You can then select from the subsystems that are available, Network, Scheduler, USB, etc. Note that you will need to
+separately enable the subsystem elsewhere in the ``menuconfig`` system. To see the ``CONFIG`` define that is set,
+use the arrow keys to highlight the subsystem (for instance, ``Network Debug Features``) and type '?'. This will show
+you that the C macro that is set is called ``CONFIG_DEBUG_NET``. ``debug.h`` defines the ``netinfo()`` logging
+function that will log output if this macro is set. You can search the source code for ``netinfo`` to see how it is
+used.
+
+.. image:: ../_static/images/menuconfig-debug.png
+    :width: 800px
+    :align: center
+    :alt: Screenshot of menuconfig system main screen
+
+Note that enabling all these will produce an incredible amount of logging output. Enable the level you want and
+the area you're interested in, and leave the rest disabled, save the config, and then recompile. You can see the full
+list of debug feature logging functions in the file
+`debug.h <https://github.com/apache/incubator-nuttx/blob/master/include/debug.h>`__.
+
+Syslog timestamps can be enabled in the ``menuconfig`` system using ``Device Drivers`` > ``System Logging`` > ``Prepend
+timestamp to syslog message`` (``CONFIG_SYSLOG_TIMESTAMP``).
 
 You may need to do a little bit of experimenting to find the combination of logging settings that work for the problem
-you're trying to solve. See the file `debug.h <https://github.com/starcat-io/incubator-nuttx/blob/master/include/debug.h>`_
+you're trying to solve. See the file `debug.h <https://github.com/apache/incubator-nuttx/blob/master/include/debug.h>`_
 for available debug settings that are available. This can also be configured via the ``menuconfig`` system.
 
 There are also subsystems that enable USB trace debugging, and you can log to memory too, if you need the logging to be
@@ -49,63 +60,33 @@ Changing Debug Settings Quickly
 You can use the ``kconfig-tweak`` script that comes with the ``kconfig-frontends`` tools to quickly change debug settings,
 for instance turning them on or off before doing a build:
 
-.. code-block:: bash
+.. code-block:: console
 
    $ kconfig-tweak --disable CONFIG_DEBUG_NET
+   $ make olddefconfig  # needed to have the kconfig system check the config
    $ kconfig-tweak --enable CONFIG_DEBUG_NET
+   $ make olddefconfig
 
 You can put a bunch of these into a simple script to configure the logging the way you want:
 
-.. code-block:: bash
+.. code-block:: console
 
    #!/bin/bash
 
-   $ kconfig-tweak --disable CONFIG_DEBUG_ALERT
+   kconfig-tweak --disable CONFIG_DEBUG_ALERT
-   $ kconfig-tweak --disable CONFIG_DEBUG_FEATURES
+   kconfig-tweak --disable CONFIG_DEBUG_FEATURES
-   $ kconfig-tweak --disable CONFIG_DEBUG_ERROR
+   kconfig-tweak --disable CONFIG_DEBUG_ERROR
-   $ kconfig-tweak --disable CONFIG_DEBUG_WARN
+   kconfig-tweak --disable CONFIG_DEBUG_WARN
-   $ kconfig-tweak --disable CONFIG_DEBUG_INFO
+   kconfig-tweak --disable CONFIG_DEBUG_INFO
-   $ kconfig-tweak --disable CONFIG_DEBUG_ASSERTIONS
+   kconfig-tweak --disable CONFIG_DEBUG_ASSERTIONS
-   $ kconfig-tweak --disable CONFIG_DEBUG_NET
+   kconfig-tweak --disable CONFIG_DEBUG_NET
-   $ kconfig-tweak --disable CONFIG_DEBUG_NET_ERROR
+   kconfig-tweak --disable CONFIG_DEBUG_NET_ERROR
-   $ kconfig-tweak --disable CONFIG_DEBUG_NET_WARN
+   kconfig-tweak --disable CONFIG_DEBUG_NET_WARN
-   $ kconfig-tweak --disable CONFIG_DEBUG_NET_INFO
+   kconfig-tweak --disable CONFIG_DEBUG_NET_INFO
-   $ kconfig-tweak --disable CONFIG_DEBUG_SYMBOLS
+   kconfig-tweak --disable CONFIG_DEBUG_SYMBOLS
-   $ kconfig-tweak --disable CONFIG_DEBUG_NOOPT
+   kconfig-tweak --disable CONFIG_DEBUG_NOOPT
-   $ kconfig-tweak --disable CONFIG_SYSLOG_TIMESTAMP
+   kconfig-tweak --disable CONFIG_SYSLOG_TIMESTAMP
-
+   make oldconfig
-Custom Debug Logging
---------------------
-
-Sometimes you need to see debug logs specific to your feature, and you don't want the rest of the built-in logs
-because they're either not relevant or have too much information. Debugging using logs is surprisingly powerful.
-
-
-You can add your own custom debug logging by adding the following lines to
-`debug.h <https://github.com/apache/incubator-nuttx/blob/master/include/debug.h>`__:
-
-.. code-block:: c
-
-   /* after the CONFIG_DEBUG_WATCHDOG_INFO block near line 721 */
-   #ifdef CONFIG_DEBUG_CUSTOM_INFO
-   #  define custinfo    _info
-   #else
-   #  define custinfo    _none
-   #endif
-
-You need to add the following line to your ``.config`` file:
-
-.. code-block:: c
-
-   CONFIG_DEBUG_CUSTOM_INFO=y
-
-You would use it like this:
-
-.. code-block:: c
-
-   /* Custom debug logging */
-   custinfo("This is a custom log message.");
-   custinfo("Custom log data: %d", my-integer-variable);
 
 
 JTAG Debugging

Documentation/quickstart/index.rst

@@ -1,5 +1,3 @@
-.. todo::
-
 ===============
 Getting Started
 ===============

Documentation/quickstart/install.rst

@@ -24,12 +24,11 @@ Install prerequisites for building using Linux
         libgmp-dev libmpc-dev libmpfr-dev libisl-dev binutils-dev libelf-dev \
         libexpat-dev gcc-multilib g++-multilib picocom u-boot-tools util-linux
 
-
 #. Give yourself access to the serial console device
 
    This is done by adding your Linux user to the ``dialout`` group:
 
- .. code-block:: bash
+    .. code-block:: console
 
        $ sudo usermod -a -G dialout $USER
        $ # now get a login shell that knows we're in the dialout group:
@@ -82,11 +81,25 @@ There are a collection of required tools that need to be built to build most Apa
 
 *NOTE:* You will need to add ``NUTTXTOOLS_PATH`` to your environment ``PATH``
 
+#. Install gperf tool
+
+   This required to build ``kconfig-frontends``.
+
+   .. code-block:: console
+
+      $ cd tools/
+      $ wget http://ftp.gnu.org/pub/gnu/gperf/gperf-3.1.tar.gz
+      $ tar zxf gperf-3.1.tar.gz
+      $ cd gperf-3.1
+      $ ./configure --prefix=$NUTTXTOOLS
+      $ make
+      $ make install
+
 #. Install kconfig-frontends tool
 
    This is necessary to run the ``./nuttx/tools/configure.sh`` script as well as using the ncurses-based menuconfig system.
 
- .. code-block:: bash
+   .. code-block:: console
 
       $ cd tools/
       $ cd kconfig-frontends
@@ -99,26 +112,12 @@ This is necessary to run the ``./nuttx/tools/configure.sh`` script as well as us
       $ make
       $ make install
 
-#. Install gperf tool
-
-   This required to build ``kconfig-frontends``.
-
- .. code-block:: bash
-
-    $ cd tools/
-    $ wget http://ftp.gnu.org/pub/gnu/gperf/gperf-3.1.tar.gz
-    $ tar zxf gperf-3.1.tar.gz
-    $ cd gperf-3.1
-    $ ./configure --prefix=$NUTTXTOOLS
-    $ make
-    $ make install
-
 #. Install gen-romfs (optional)
 
 
    This is required if you want to build ROM-based file systems.
 
- .. code-block:: bash
+   .. code-block:: console
 
       $ cd tools/
       $ tar zxf genromfs-0.5.2.tar.gz
@@ -138,7 +137,7 @@ to use it, modify it or help develop it, you'll need the source code.
 
 You can either clone the public repositories:
 
-    .. code-block:: bash
+.. code-block:: console
 
    $ mkdir nuttx
    $ cd nuttx
@@ -147,7 +146,7 @@ You can either clone the public repositories:
 
 Or, download the `tarball <https://github.com/apache/incubator-nuttx/tarball/master>`_:
 
-    .. code-block:: bash
+.. code-block:: console
 
    $ curl -OL https://github.com/apache/incubator-nuttx/tarball/master
    $ curl -OL https://github.com/apache/incubator-nuttx-apps/tarball/master
@@ -168,12 +167,12 @@ binary file on your embedded computer. This guide assumes your computer is an
    `script <https://github.com/apache/incubator-nuttx-testing/blob/master/cibuild.sh>`_ and Docker `container <https://github.com/apache/incubator-nuttx-testing/blob/master/docker/linux/Dockerfile>`_
 
 Download the right flavor of the
-`ARM Embedded Gnu Toolchain <https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm>`_
+`ARM Embedded GNU Toolchain <https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm>`_
 for your embedded processor's CPU.
 
 Unpack it into ``/opt/gcc`` and add the bin directory to your path. For instance:
 
- .. code-block:: bash
+.. code-block:: console
 
    $ usermod -a -G users $USER
    $ # get a login shell that knows we're in this group:

Documentation/quickstart/organization.rst

@@ -241,6 +241,8 @@ execute them.
 
 The ``audio/`` subdirectory contains the NuttX audio sub-system.
 
+.. _nuttx_boards:
+
 ``nuttx/boards``
 ================
 

Documentation/quickstart/quickstart.rst

@@ -15,11 +15,10 @@ computer, you're using an ARM microcontroller on your embedded board, and you're
    `ARM <https://en.wikipedia.org/wiki/ARM_architecture>`_ CPU. If it isn't, you'll need a different tool chain.
 
    You can download a toolchain from
-   `ARM Embedded Gnu Toolchain <https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm>`_
+   `ARM Embedded GNU Toolchain <https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm>`_
    for your embedded processor's CPU. You can also use a toolchain shipped with your OS for the `none-eabi` target, such as `gcc-arm-none-eabi` in Linux.
 
-
+   In the following example, we download ``gcc-arm-none-eabi`` version 9.0 and unpack it into ``/opt/gcc``:
-In the following example, we download ``gcc-arm-none-eabi`` version 9.0 and unpack it into ``/opt/gcc`:
 
    .. code-block:: console
 
@@ -38,7 +37,9 @@ Then, add the toolchain ``bin/`` directory to your path:
    If you are using any other shell, the procedure is similar by editing the corresponding rc file.
 
 #. Download Apache NuttX
+
    The next step is to download NuttX main repository along the application repository. The latter is technically optional in a very minimal configurations but should be included in normal configuration since it includes the NuttX shell.
+
    .. code-block:: console
 
       $ mkdir nuttx

Documentation/quickstart/running.rst

@@ -22,10 +22,10 @@ You can load code, start, stop, step through the program, and examine variables
 
        $ JLinkGDBServer -device ATSAMA5D27 -if JTAG -speed 1000 -JTAGConf -1,-1
 
-#. Launch the Gnu Debugger
+#. Launch the GNU Debugger
 
    In another terminal window, launch the GDB for your platform. In the case of this guide, this came with the
-   ARM Embedded Gnu Toolchain we downloaded in the Install step.
+   ARM Embedded GNU Toolchain we downloaded in the Install step.
 
     .. code-block:: bash