doc: Clean up and improve documentation#661
Merged
Merged
Conversation
|
✅Static analysis result - no issues found! ✅ |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
The docs had grown organically into a flat
doc/en/directory where ~23category folders (
imu/,display/,network/, …) coexisted with ~53individual component pages dumped at the top level, and the master
index.rstinterleaved both in one ~80-entry toctree. This reorganizes the documentation
around a consistent, discoverable structure without changing any component
content.
Navigation — the master
index.rstis now grouped into captioned sections:Introduction · Core & RTOS · Storage & Configuration · Buses & I/O · Sensors ·
Motor Control · Displays, LEDs & Haptics · Input & HID · Connectivity &
Protocols · Math & DSP · Data & Serialization · Dev Boards (BSPs).
Structure changes:
_example.mdcompanions) intocategory folders via
git mv(history preserved): newcore/,storage/,buses/,leds/,motor_control/,data/,protocols/; folded inputdevices into
input/andcolorintomath/.dev_boards/section collecting all 19 board-support packages, groupedby vendor (Espressif, Adafruit, LilyGo, M5Stack, MotorGo, Seeed, Waveshare,
Other) — previously these were scattered through the flat top-level list.
getting_started.rst) surfacing theinstall/usage info that previously only lived in the repo README.
index.rstlanding pages and cross-links between relatedareas (LEDs↔led_driver, Motor Control↔bldc↔filters, MotorGo boards↔motor
control, Math↔filters, Protocols↔network).
Component manifests:
documentation:URL in 57idf_component.ymlfiles to the new docpaths (e.g.
spi.html→buses/spi.html,button.html→input/button.html,board pages →
dev_boards/<vendor>/…), including the sharedloggerpageanchors used by the
logger,format, andbinary-logcomponents.Motivation and Context
A reader scanning the old top-level index couldn't tell what the categories were
or where to find a board vs. a driver vs. a utility, and 16+ dev boards were
buried among system components. Grouping by capability (plus a dedicated Dev
Boards section and a Getting Started landing page) makes the docs navigable and
gives every page a consistent home. No API or example content changed — only
where pages live and how they're linked.
How has this been tested?
reachable from
index.rst, with no orphaned pages and no broken toctreereferences, and all RST title underlines are valid.
include-build-file:: inc/…resolves from a fixed build root (not file-relative),
\snippetuses Doxygenexample IDs, and each
.rstmoved together with its_example.mdsodocument-relative toctrees stay valid.
documentation:links across the component manifestsresolve to real pages on disk (116 valid, 0 broken).
./build_docs.sh) and visually reviewed therendered navigation.
Screenshots (if appropriate):
Types of changes
Checklist: