mirror of
https://github.com/apache/nuttx.git
synced 2026-10-08 06:45:19 +00:00
f6ecf80ebb
The documentation grew one page at a time, so the tree follows the
history of who wrote what and not the shape of NuttX. Scheduling is
spread over three places, a driver page can sit above the subsystem
that owns it, and the front page lists everything at the same level.
That is a lot to face when all you want to know is where the scheduler
lives.
This change files every page under the code it describes. It is a move,
not a rewrite: outside the ten pages named below, every page keeps the
text that is already in master, and no page's text is deleted.
What it does:
* Groups the table of contents into nine chapters.
* Moves the OS subsystems under os/: scheduling, memory, drivers,
filesystem, networking, IPC, interrupts, libs, time.
* Renames the platform pages to the names the source tree uses, and
derives their tags from the tree instead of by hand.
* Splits guides/ by subject.
* Adds Documentation/redirects.py, with a rule for every page that left
its old path, so old URLs keep working. The redirect page also carries
a link's #anchor across to the new page.
Ten pages have text that is new or rewritten. Nine of them are the
landing page of a chapter, which has to exist for the new structure:
index the front page
os/index OS Design
os/scheduling/index Scheduling
os/interrupts/index Interrupts
os/ipc/index IPC
os/time/index Time and timers
about/index About
developing/index Developing NuttX
ReleaseNotes/index Release notes
The tenth is os/libs/libbuiltin, the only page here with technical
content: libs/libbuiltin/ had no page at all. Five SVG diagrams come
with these pages, hand-written XML with no editor metadata.
Nothing outside Documentation/ is touched.
How it was checked:
* Sphinx builds with -W: no warnings, and no document left outside a
toctree.
* A script, offered in the PR, proves the narrow claim this rests on.
For every page outside the ten named above it erases what a move
touches -- link target, path, tag line, toctree block, table border --
from the whole old text and the whole new text, and requires the two
to be byte for byte identical. It also requires every sentence of a
deleted page to turn up somewhere, and every page that left its old
path to have a redirect, from a URL that existed, to where its content
went. It exits non-zero and names the page if any of that is not true,
and it tests added pages too, so forgetting to declare one cannot make
it pass.
* An independent audit checked 133 factual claims on these ten pages
against the tree, one shell command per claim: 130 confirmed, 1
refuted and fixed here, 2 not checkable.
* tools/checkpatch.sh is clean over the range.
The diff is large because moving a page changes every link that points
to it. Most of it is pure renames, and board pages that gained one tag
line.
Assisted-by: Claude:claude-opus-5
151 lines
4.9 KiB
ReStructuredText
151 lines
4.9 KiB
ReStructuredText
===================
|
||
NuttX Documentation
|
||
===================
|
||
|
||
NuttX is a real-time operating system (RTOS) with an emphasis on standards
|
||
compliance and small footprint. Scalable from 8-bit to 64-bit microcontroller
|
||
environments, the primary governing standards in NuttX are POSIX and ANSI
|
||
standards. Additional standard APIs from Unix and other common RTOS’s (such as
|
||
VxWorks) are adopted for functionality not available under these standards, or
|
||
for functionality that is not appropriate for deeply-embedded environments (such
|
||
as fork()).
|
||
|
||
Where to start
|
||
==============
|
||
|
||
.. grid:: 1 2 2 3
|
||
:gutter: 3
|
||
|
||
.. grid-item-card:: :octicon:`rocket;1.2em;sd-text-primary` Getting Started
|
||
:link: quickstart/index
|
||
:link-type: doc
|
||
|
||
Install the toolchain, build for a board, get a shell.
|
||
Start here if you have never built NuttX.
|
||
|
||
.. grid-item-card:: :octicon:`cpu;1.2em;sd-text-primary` Supported Platforms
|
||
:link: platforms/index
|
||
:link-type: doc
|
||
|
||
Every architecture, chip and board NuttX runs on.
|
||
Start here if you have hardware in your hand.
|
||
|
||
.. grid-item-card:: :octicon:`checklist;1.2em;sd-text-primary` Guides
|
||
:link: guides/index
|
||
:link-type: doc
|
||
|
||
How to do a particular thing: port, write a driver, debug.
|
||
Start here when you know what you want to build.
|
||
|
||
Understanding the system
|
||
========================
|
||
|
||
.. grid:: 1 2 2 3
|
||
:gutter: 3
|
||
|
||
.. grid-item-card:: :octicon:`stack;1.2em;sd-text-primary` OS Design
|
||
:link: os/index
|
||
:link-type: doc
|
||
|
||
How NuttX is built, subsystem by subsystem.
|
||
|
||
.. grid-item-card:: :octicon:`book;1.2em;sd-text-primary` API Reference
|
||
:link: reference/index
|
||
:link-type: doc
|
||
|
||
The POSIX and NuttX calls an application may make.
|
||
|
||
.. grid-item-card:: :octicon:`apps;1.2em;sd-text-primary` Applications
|
||
:link: applications/index
|
||
:link-type: doc
|
||
|
||
The programs that ship with NuttX, from NSH onwards.
|
||
|
||
Working on NuttX
|
||
================
|
||
|
||
.. grid:: 1 2 2 2
|
||
:gutter: 3
|
||
|
||
.. grid-item-card:: :octicon:`tools;1.2em;sd-text-primary` Developing NuttX
|
||
:link: developing/index
|
||
:link-type: doc
|
||
|
||
Getting a change accepted, the build system, porting, testing.
|
||
|
||
.. grid-item-card:: :octicon:`info;1.2em;sd-text-primary` About
|
||
:link: about/index
|
||
:link-type: doc
|
||
|
||
Questions, vocabulary, security reports, release notes.
|
||
|
||
How this documentation is organised
|
||
===================================
|
||
|
||
Four ideas decide where anything goes. They are written down here because
|
||
knowing them turns "where do I look?" into a question with an answer -- and,
|
||
for anyone writing documentation, "where do I put this?" as well.
|
||
|
||
**The sections follow what you are doing, not what NuttX contains.**
|
||
Arriving, finding your hardware, doing a task, understanding a subsystem,
|
||
looking up a call: those are different activities, and each has a section.
|
||
Guides comes before OS Design on purpose, because people want something
|
||
running before they want to know how the scheduler works.
|
||
|
||
**Three different questions, three different sections.** It is the same
|
||
subject seen three ways, and mixing them is what makes documentation hard to
|
||
search:
|
||
|
||
.. list-table::
|
||
:header-rows: 1
|
||
:widths: 22 30 48
|
||
|
||
* - Section
|
||
- Answers
|
||
- For example
|
||
* - :doc:`Guides <guides/index>`
|
||
- *How do I do X?*
|
||
- How to mount a ROMFS image at ``/etc``
|
||
* - :doc:`OS Design <os/index>`
|
||
- *How does X work?*
|
||
- How the scheduler picks the next thread
|
||
* - :doc:`API Reference <reference/index>`
|
||
- *What may I call?*
|
||
- What ``sched_setscheduler()`` takes and returns
|
||
|
||
**OS Design follows the source tree.** Each top level directory of NuttX --
|
||
``sched/``, ``fs/``, ``net/``, ``mm/``, ``drivers/`` -- is a section, and
|
||
each subsystem is described once, going from what it is, to how it works, to
|
||
the interfaces it offers. That is why there is one page about SMP rather
|
||
than three, and why a contributor knows which page to add to.
|
||
|
||
**What can be derived is derived, and checked.** Board pages, the
|
||
architecture and chip each one is filed under, and the tags that let you
|
||
search for them all come from the source tree rather than being typed by
|
||
hand, and the build fails when the two disagree. A page describing a board
|
||
that no longer exists, or a board with no page, does not survive the next
|
||
pull request.
|
||
|
||
.. note::
|
||
Something wrong on a page, or missing? The documentation lives in the
|
||
same repository as the code, and every page has an *Edit on GitHub* link
|
||
at the top right. See :doc:`contributing/documentation` for how to build
|
||
it locally.
|
||
|
||
.. toctree::
|
||
:caption: Table of Contents
|
||
:maxdepth: 2
|
||
:hidden:
|
||
|
||
Home <self>
|
||
introduction/index.rst
|
||
quickstart/index.rst
|
||
platforms/index.rst
|
||
guides/index.rst
|
||
os/index.rst
|
||
reference/index.rst
|
||
applications/index.rst
|
||
developing/index.rst
|
||
about/index.rst
|
||
|
||
.. include:: substitutions.rst
|