Documentation: various cosmetic changes

Documentation/components/drivers/character/analog.rst

@@ -16,7 +16,7 @@ The NuttX analog drivers are split into two parts:
 -  Common analog logic and share-able analog drivers reside in the
    ``drivers/analog/``.
 -  Platform-specific drivers reside in
-   ``arch/<architecture>//src/<hardware>`` directory
+   ``arch/<architecture>/src/<hardware>`` directory
    for the specific processor ``<architecture>`` and for the
    specific ``<chip>`` analog peripheral devices.
 

Documentation/components/drivers/index.rst

@@ -277,9 +277,9 @@ Skeleton Files
 
 Skeleton files are "empty" frameworks for NuttX drivers.  They are provided to
 give you a good starting point if you want to create a new NuttX driver.
-The following skeleton files are available::
+The following skeleton files are available:
 
-  drivers/lcd/skeleton.c -- Skeleton LCD driver
+* ``drivers/lcd/skeleton.c`` Skeleton LCD driver
-  drivers/mtd/skeleton.c -- Skeleton memory technology device drivers
+* ``drivers/mtd/skeleton.c`` Skeleton memory technology device drivers
-  drivers/net/skeleton.c -- Skeleton network/Ethernet drivers
+* ``drivers/net/skeleton.c`` Skeleton network/Ethernet drivers
-  drivers/usbhost/usbhost_skeleton.c -- Skeleton USB host class driver
+* ``drivers/usbhost/usbhost_skeleton.c`` Skeleton USB host class driver

Documentation/components/libs/index.rst

@@ -34,7 +34,6 @@ container.
 The only real function of the ``libs/`` directory is to prevent the top-level
 directory from becoming cluttered with individual libraries.
 
-
 .. toctree::
    :maxdepth: 1
    :caption: Contents:

Documentation/contributing/index.rst

@@ -1,3 +1,4 @@
+============
 Contributing
 ============
 

Documentation/contributing/making-changes.rst

@@ -1,6 +1,7 @@
 .. include:: /substitutions.rst
 .. _making-changes:
 
+========================
 Making Changes Using Git
 ========================
 
@@ -65,7 +66,7 @@ Here's how to do it:
        $ git push
 
 Git Workflow With an Upstream Repository
-----------------------------------------
+========================================
 
 The main NuttX git repository is called an "upstream" repository - this is because it's the main source of truth, and
 its changes flow downstream to people who've forked that repository, like us.
@@ -160,7 +161,7 @@ maybe doing that several times. Then when everything works, I get my branch read
        $ git push
 
 Submitting Your Changes to NuttX
---------------------------------
+================================
 
   Pull requests let you tell others about changes you've pushed to a branch in a repository on GitHub. Once a pull
   request is opened, you can discuss and review the potential changes with collaborators and add follow-up commits
@@ -212,7 +213,7 @@ squash before submitting the Pull Request:
    1 through 6.
 
 How to Include the Suggestions on Your Pull Request?
-----------------------------------------------------
+====================================================
 
 If you submitted your first PR (Pull Request) and received some feedbacks
 to modify your commit, then probably you already modified it and created a
@@ -344,7 +345,7 @@ Now you can look at your PR at NuttX's github to confirm that
 this squashed commit is there.
 
 Git Resources
--------------
+=============
 
 * `Git Cheat Sheet (by GitHub) <https://github.github.com/training-kit/downloads/github-git-cheat-sheet.pdf>`_
 * `Git Book (online) <https://git-scm.com/book/en/v2>`_

Documentation/contributing/workflow.rst

@@ -1,5 +1,6 @@
 .. todo:: update when workflow is settled
 
+====================
 Development Workflow
 ====================
 

Documentation/guides/coredump.rst

@@ -1,6 +1,6 @@
-====================
+=========
 Core Dump
-====================
+=========
 
 Overview
 ========

Documentation/guides/cpp_cmake.rst

@@ -1,6 +1,7 @@
 .. include:: /substitutions.rst
 .. _cpp_cmake:
 
+=======================
 C++ Example using CMake
 =======================
 
@@ -24,7 +25,7 @@ applications using C++ language and also the cmake build tool.
 This document will show how to reimplement the hellocpp project using this cmake.
 
 Preparation
------------
+===========
 
 #. Base NuttX compilation changes
 
@@ -46,7 +47,7 @@ Preparation
        $ make export
 
 Creating the project
---------------------
+====================
 
 #. Create your project file structure
 
@@ -268,7 +269,7 @@ Creating the project
     }
 
 Building
---------
+========
 
 To launch build, you use the cmake procedure:
 

Documentation/guides/customapps.rst

@@ -18,9 +18,8 @@ the directory ``CustomApps`` as an example.
   need to run ``make clean`` and possibly even ``make distclean`` before rebuilding to
   ensure it works correctly.
 
------------------------------------------
 1. Replace The Apps/ Directory Completely
------------------------------------------
+=========================================
 
 The CustomApps directory need only to contain the minimum three files:
 
@@ -188,9 +187,8 @@ Then build as you normally would. When you execute the custom_hello app you shou
 
     Hello, Custom World!!
 
----------------------------------------------------------------
 2. Extend the apps/ directory to include a new custom directory
----------------------------------------------------------------
+===============================================================
 
 The collection of apps provided in nuttx-apps can be useful, and this method simply
 extends the directory structure to include your own directory structure.
@@ -306,9 +304,8 @@ followed by ``make menuconfig``. If successful there will be new Kconfig entries
 Select the ``Custom Hello App`` and run the usual build process. If successful
 you can run the newly included ``custom_hello`` app.
 
---------------------------------------------------------------------------
 3. Include an Additional Custom directory Outside of the Main Source Trees
---------------------------------------------------------------------------
+==========================================================================
 
 Thia is similar to the previous approach, but places the ``CustomApps`` directory
 outside of the default trees.

Documentation/guides/customboards.rst

@@ -17,9 +17,8 @@ Sometimes it is not appropriate, or not wanted, to add a new or custom board to
 the NuttX boards tree itself. If so, the board can be defined out-of-tree in a
 custom directory and still be built easily.
 
-------------------
 Add a Custom Board
-------------------
+==================
 
 The same set of files as provided for in-tree boards is required (i.e. configs,
 Kconfig, scripts, etc.) but these can be placed in a directory of your choice.
@@ -53,7 +52,7 @@ To build the custom board, the syntax is slightly different to in-tree boards an
       Refreshing...
 
 Kconfig Settings
-----------------
+================
 
 Once the board is configured, to ensure subsequent builds run correctly, there
 are two Kconfig settings that need to be set. These are:

Documentation/guides/drivers.rst

@@ -1,6 +1,7 @@
 .. include:: /substitutions.rst
 .. _drivers:
 
+=======
 Drivers
 =======
 
@@ -10,7 +11,7 @@ you will either need to port a driver from another chip, or write one yourself.
 .. _drivers-porting:
 
 Porting a Driver
-----------------
+================
 
 Often support for on-chip peripherals exists in a closely related chip, or even a different family or from a different
 manufacturer. Many chips are made up of different Intellectual Property (IP) blocks that are licensed from vendors like
@@ -144,7 +145,7 @@ modification.
         200aaaa0: 0000 0000 0000 0000                      ........
 
 NuttX Drivers as a Reference
-----------------------------
+============================
 
 If you're not porting a NuttX driver from another architecture, it still helps to look at other similar NuttX
 drivers, if there are any. For instance, when implementing an Ethernet driver, look at other NuttX Ethernet drivers;
@@ -152,7 +153,7 @@ for an SD Card driver, look at other NuttX SD Card drivers. Even if the chip-spe
 structure to interface with NuttX can be used.
 
 Using Chip Datasheets
----------------------
+=====================
 
 To port or write a driver, you'll have to be familiar with the information in the chip datasheet. Definitely find
 the datasheet for your chip, and read the sections relevant to the peripheral you're working with. Doing so ahead
@@ -179,7 +180,7 @@ code implements the necessary algorithms often helps one understand how the driv
       examples.
 
 Logic Analyzers
----------------
+===============
 
 For drivers that involve input and output (I/O), especially that involve complex protocols like SD Cards, SPI, I2C,
 etc., actually seeing the waveform that goes in and out the chip's pins is extremely helpful. `Logic Analyzers <https://en.wikipedia.org/wiki/Logic_analyzer>`_
@@ -187,7 +188,7 @@ can capture that information and display it graphically, allowing you to see if
 on the wire.
 
 DMA Debugging
--------------
+=============
 
 * Dump registers before, during, and after transfer. Some NuttX drivers (``sam_sdmmc.c`` or ``imxrt_sdmmc.c`` for
   example) have built-in code for debugging register states, and can sample registers before, during, and

Documentation/guides/gdbwithpython.rst

@@ -1,6 +1,6 @@
-====================
+===============
 GDB with Python
-====================
+===============
 
 Introduction
 ============

Documentation/guides/index.rst

@@ -1,6 +1,7 @@
 .. todo::
   Create "tutorial" type documentation for specific subjects not to be covered in more general terms.
 
+======
 Guides
 ======
 

Documentation/guides/ofloader.rst

@@ -3,7 +3,7 @@ Open Flash Loader
 =================
 
 Introduce
-=====================================
+=========
 
 Open Flash loader is an implementation in NuttX that bridges the device
 drivers in NuttX with the programming methods of a flash loader in J-Link.

Documentation/guides/pysimcoder.rst

@@ -1,6 +1,7 @@
 .. include:: /substitutions.rst
 .. _pysimcoder:
 
+=================================
 pysimCoder integration with NuttX
 =================================
 
@@ -16,7 +17,7 @@ This documentation describes the steps that are needed to run application genera
 on NuttX and also keeps the track of peripherals that are supported by pysimCoder for NuttX RTOS.
 
 Peripheral Support
-------------------
+==================
 
 The following list shows the peripherals and fuctionalities supported in pysimCoder for NuttX RTOS.
 
@@ -39,7 +40,7 @@ Please note that the actual support for NuttX peripherals can be wider that what
 in case this documentation was not updated when new fuctionalities were added to pysimCoder.
 
 NuttX Configuration
--------------------
+===================
 
 Several configuration options are necessary to be set in order to successfully compile pysimCoder
 with NuttX. The list is the following:
@@ -124,7 +125,7 @@ Please note that PYSUPSICTRL variable has to be set/exported in order to success
 designed with pysimCoder.
 
 Using pysimCoder to design NuttX application
---------------------------------------------
+============================================
 
 After running pysimCoder, separate blocks can be selected from the library menu on the left hand side. The menu contains
 several libraries, NuttX specific blocks can be found in library "NuttX". It is also possible to use blocks from other

Documentation/guides/qemugdb.rst

@@ -1,6 +1,7 @@
 .. include:: /substitutions.rst
 .. _qemugdb:
 
+=====================================
 How to debug NuttX using QEMU and GDB
 =====================================
 
@@ -11,7 +12,7 @@ board or architecture supported by QEMU.
 Start configuring and compiling the lm3s6965-ek board with qemu-flat profile.
 
 Compiling
----------
+=========
 
 #. Configure the lm3s6965-ek
 
@@ -31,7 +32,7 @@ Compiling
        $ make -j
 
 Start QEMU
-----------
+==========
 
 #. You need to start QEMU using the nuttx ELF file just create above:
 
@@ -46,7 +47,7 @@ Start QEMU
        nsh>
 
 Start GDB to connect to QEMU
-----------------------------
+============================
 
    These steps show how to connect GDB to QEMU running NuttX:
 

Documentation/guides/rndis.rst

@@ -1,6 +1,7 @@
 .. include:: /substitutions.rst
 .. _rndis:
 
+================
 How to use RNDIS
 ================
 
@@ -17,7 +18,7 @@ risk and also be aware that it was tested up to Ubuntu 22.04 LTS and
 couldn't work in future versions.
 
 Compiling
----------
+=========
 
 #. Configure the RNDIS
 
@@ -39,7 +40,7 @@ Compiling
        $ make -j
 
 Flashing
---------
+========
 
 #. Flash the generated nuttx.bin to your board:
 
@@ -65,7 +66,7 @@ Flashing
 
 
 Setup RNDIS in your computer
-----------------------------
+============================
 
    These steps show how to connect your board to your Linux machine.
 

Documentation/guides/simulator.rst

@@ -1,6 +1,7 @@
 .. include:: /substitutions.rst
 .. _simulator:
 
+=========
 Simulator
 =========
 
@@ -16,7 +17,7 @@ submit a PR to improve this guide!
 .. todo:: Windows instructions
 
 Prerequisites For macOS
------------------------
+=======================
 
 We need ``genromfs`` to build simulators(NON GUI).
 
@@ -37,7 +38,7 @@ For GUI Applications we need X11 Libraries, libx11 can also be built using Homeb
       $ sudo port install xorg-server
 
 Compiling
----------
+=========
 
 #. Configure the Simulator
 
@@ -94,7 +95,7 @@ Compiling
 .. _simulator_accessing_the_network:
 
 Accessing the Network
----------------------
+=====================
 
 #. Here we'll use the ``sim:tcpblaster`` configuration because it comes with networking
    that is ready to use.
@@ -202,7 +203,7 @@ Accessing the Network
    Success!
 
 Testing / capturing TCP network traffic
----------------------------------------
+=======================================
 
 #. Start Wireshark (or tcpdump) on Linux and capture the appeared tap0 interface.
 
@@ -228,7 +229,7 @@ Testing / capturing TCP network traffic
 #. Observe TCP network traffic in Wireshark / tcpdump on Linux.
 
 Stopping
---------
+========
 
 #. The normal way to stop:
 
@@ -257,6 +258,6 @@ Stopping
        $ sudo ./tools/simhostroute.sh wlan0 off
 
 Debugging
----------
+=========
 
 You can debug the simulator like any regular Linux program.

Documentation/introduction/index.rst

@@ -1,3 +1,4 @@
+============
 Introduction
 ============
 

Documentation/introduction/resources.rst

@@ -22,4 +22,5 @@ Here's a list of Apache NuttX resources that you might find helpful:
 
 Legacy README
 =============
+
 .. mdinclude:: ../legacy_README.md

Documentation/quickstart/configuring.rst

@@ -1,6 +1,7 @@
 .. include:: /substitutions.rst
 .. _configuring:
 
+===========
 Configuring
 ===========
 
@@ -93,7 +94,7 @@ computer.
    configured in :menuselection:`Application Configuration --> NSH Library --> Message of the Day (MOTD)`.
    
 Fast configuration changes
---------------------------
+==========================
 
 If you know exactly which configuration symbol you want to change, you can use the ``kconfig-tweak`` tool (comes with the ``kconfig-frontends`` package) to quickly change a setting without going into the configuration frontend. This is useful to change settings such as debug options:
 
@@ -126,7 +127,7 @@ This is also useful to script configuration changes that you perform often:
    make oldconfig
 
 Reference configuration
---------------------------
+=======================
 
 Defconfig supports the use of ``#include`` statements to reference other configuration files:
 
@@ -144,7 +145,7 @@ The default header file search path includes:
 * ``${boards}/common/configs``;
 
 Merge configuration
---------------------------
+===================
 
 Multiple config fragments can be merged manually using the tools/merge_config.py script.
 

Documentation/reference/os/newreno.rst

@@ -13,7 +13,6 @@ NewReno congestion control algorithm is used to solve the problem of network con
 Workflow
 ========
 
-
 The NewReno on the tcp sender adjusts the cwnd and ssthresh based on received ack and Retransmitted Timeout (RTO) events.
 
 Using the cwnd, together with snd_wnd, controls the number of bytes sent to the network. Here's how newreno works, as following:

Documentation/reference/user/02_task_scheduling.rst

@@ -1,5 +1,6 @@
+==========================
 Task Scheduling Interfaces
-**************************
+==========================
 
 By default, NuttX performs strict priority scheduling: Tasks of higher
 priority have exclusive access to the CPU until they become blocked. At
@@ -29,7 +30,7 @@ compliant interface to the NuttX scheduler:
   - :c:func:`sched_get_rr_interval`
 
 Functions
----------
+=========
 
 .. c:function:: int sched_setparam(pid_t pid, FAR const struct sched_param *param)
 

Documentation/reference/user/06_clocks_timers.rst

@@ -1,5 +1,6 @@
+=================
 Clocks and Timers
-*****************
+=================
 
 - :c:func:`clock_settime`
 - :c:func:`clock_gettime`

Documentation/reference/user/07_signals.rst

@@ -1,5 +1,6 @@
+=================
 Signal Interfaces
-*****************
+=================
 
 **Tasks and Signals**. NuttX provides signal interfaces for tasks and
 pthreads. Signals are used to alter the flow control of tasks by

Documentation/reference/user/12_shared_memory.rst

@@ -1,5 +1,6 @@
+========================
 Shared Memory Interfaces
-************************
+========================
 
 Shared memory interfaces are only available with the NuttX kernel build
 (``CONFIG_BUILD_KERNEL=y``). These interfaces support user memory
@@ -12,7 +13,7 @@ memory interfaces:
   - :c:func:`shmdt`
 
 Functions
----------
+=========
 
 .. c:function:: int shmget(key_t key, size_t size, int shmflg)
 

Documentation/reference/user/structures.rst

@@ -1,8 +1,9 @@
+==================
 OS Data Structures
 ==================
 
 Scalar Types
-************
+============
 
 Many of the types used to communicate with NuttX are simple scalar
 types. These types are used to provide architecture independence of the
@@ -15,7 +16,7 @@ include:
 .. c:type:: time_t
 
 Hidden Interface Structures
-***************************
+===========================
 
 Several of the types used to interface with NuttX are structures that
 are intended to be hidden from the application. From the standpoint of
@@ -33,7 +34,7 @@ specific elements within these hidden structures. These hidden
 structures will not be described further in this user's manual.
 
 Access to the ``errno`` Variable
-********************************
+================================
 
 A pointer to the thread-specific ``errno`` value is available through a
 function call:
@@ -61,7 +62,7 @@ function call:
     :return: A pointer to the thread-specific ``errno`` value.
 
 User Interface Structures
-*************************
+=========================
 
 .. c:type:: int (*main_t)(int argc, char *argv[])