vrmay23 opened a new pull request, #20413:
URL: https://github.com/apache/nuttx/pull/20413
*Note: this replaces #20394, which I closed myself. That PR touched the text
of 50 pages. After the review comments I cut it down to 10. The old PR stays
open to read, including the review that led to this one.*
I'm opening this PR because I strongly believe NuttX deserves a better and
more welcoming documentation, one that will pull new joiners in instead of
pushing them away.
I have spent a couple of weeks reviewing it and I came to the conclusion that
it would be impossible to do this in small changes across several commits. So
I will split this into 3 PRs, of which the first one (this one) is pretty
much
just reorganizing the documentation. Please give it a chance and see how much
better it becomes.
I really tried to only reorganize the pages we already have, but that proved
impossible as well. So 10 pages had to be introduced, otherwise this new
"outfit" would have been incomplete, and the reviewers would have complained
(rightly so).
The second PR intends to fix the issues in the documentation itself. But that
is a topic for the next PR.
Finally, yes, I have used AI to support this documentation refactor,
otherwise
it would have been pretty much impossible. The good thing is that I have
audited it as well, via scripts. That is why the information below is a
little
bit big, but from my perspective it is quite important to explain everything
that is being proposed here.
Thanks!
## Summary
**Why.**
NuttX is a small, minimalist RTOS. The documentation is not small and
not organised, and that gap is what this PR fixes.
**What this does.**
Files every page under the code it describes. Nine chapters instead of
nineteen top-level entries. Old URLs keep working through 520 redirect
rules.
**What did NOT change.**
The **text** of the pages. Of the 1573 `.rst` pages, 1563 keep the
words that are already in master. Only their address, their links and
their place in the tree changed.
**What text DID change.**
Ten pages. Nine are the landing page of a chapter, which has to exist
for the new structure. The tenth is the only one with technical
content: `libs/libbuiltin/` had no page at all.
```
index the front page os/time/index Time and
timers
os/index OS Design about/index About
os/scheduling/index Scheduling developing/index Developing
NuttX
os/interrupts/index Interrupts ReleaseNotes/index Release
notes
os/ipc/index IPC os/libs/libbuiltin
libs/libbuiltin/
```
**What else changed, and why.**
When I said "nothing has changed" was related to the documentation only.
Apart of the reorganization, even non-page files did change, and here is
each one:
| file | what | why |
|---|---|---|
| `conf.py` | +36 −1 | registers `sphinx_reredirects` and `tags_overview`;
derives the copyright year from `SOURCE_DATE_EPOCH` so the footer stops going
stale; stops `autosectionlabel` indexing the frozen release notes, which reuse
the same section titles and emitted a duplicate-label warning for every
repetition |
| `redirects.py` | new | 520 rules, one per page that moved, so no existing
URL breaks |
| `_templates/layout.html` | +22 −18 | fixes the logo, which had silently
disappeared: Sphinx renamed `logo` to `logo_url` and the template stopped
rendering it. Also drops the empty entry in the version selector caused by a
trailing comma |
| `_static/custom.css` | +267 | styling for the new tag index and the front
page cards |
| `_extensions/tags_overview.py` | new | regroups the tag index into arch >
chip > part |
| `Pipfile` / `Pipfile.lock` | +19 −1 | declares and pins
`sphinx-reredirects`. Without the lock entry, CI's `pipenv sync` would fail |
| `contributing/doc_templates/board-tags-example.txt` | new | the tag block
the board template tells you to copy, kept as its own file |
Five SVG diagrams come with the ten pages above. They are hand-written
XML: no editor metadata, no scripts, no external references.
**Table of contents, before and after.**
@cederom asked for this comparison, and I will also take it to dev@.
```
CURRENT (19 top-level) PROPOSED (9 top-level)
Introduction Introduction
Getting Started Getting Started
Contributing Supported Platforms
Inviolables Guides
Supported Platforms OS Design <- new
OS Components API Reference
Applications Applications
Implementation Details Developing NuttX <- new
API Reference About <- new
FAQ
Debugging
Testing
Guides
Standards
Security
Glossary
Logos
Tags Index
```
Nothing was deleted. Every old chapter is still there, one level down:
```
Contributing, OS Components, Implementation, Testing -> Developing NuttX
FAQ, Security, Glossary, Logos, Release Notes -> About
Debugging -> Guides
Standards -> Introduction
Inviolables -> Introduction
Tags Index -> Supported Platforms
```
## Impact
Is new feature added? NO
Is existing feature changed? NO (documentation only)
* **Users:** every page is at a new address. All 520 old URLs redirect, so
existing links and bookmarks keep working.
* **Build:** no change to the OS build. `Documentation/Pipfile` gains one
dependency, `sphinx-reredirects`, pinned in the lock file.
* **Hardware:** none. Nothing outside `Documentation/` is touched.
* **Documentation:** this is the change.
* **Security:** none.
* **Compatibility:** no source, header or Kconfig symbol is touched.
## Testing
Documentation-only change, so it is tested with `make html` as
CONTRIBUTING says, plus two checks of my own.
**Host:** Linux x86_64, Python 3.11, Sphinx 6.2.1.
**Board:** none applicable, no code is touched.
```
$ cd Documentation && make html
build succeeded.
2529 pages, 0 warnings under -W, 0 documents outside a toctree
$ python3 validate_reorg.py 53ac762e79
-- 2. .rst PAGES IN HEAD (1573) ------------------------------------------
never touched 783
changed by the move only 467
moved, byte for byte identical 310
new or rewritten text (the 10) 10
halves of one split page (section 3) 2
new, no text (toctree only) 1
TOTAL 1573
APPROVED -- the claim checked here is about CONTENT
$ # every redirect target resolves to a page that exists
520 rules, 0 broken
$ ./tools/checkpatch.sh -g 53ac762e79...HEAD
✔️ All checks pass.
```
**How you can check the "nothing changed" claim yourself.** The script is in
the first comment below. 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 exits non-zero and names the page if that is not
true, and it tests added pages too, so forgetting to declare one cannot make
it
pass.
**Audit.** 133 factual claims on those ten pages were each checked against
the
tree with one shell command: 130 confirmed, 1 refuted and fixed here, 2 not
checkable.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
