Skip to content

doc: Clean up and improve documentation#661

Merged
finger563 merged 1 commit into
mainfrom
doc/cleanup
Jun 30, 2026
Merged

doc: Clean up and improve documentation#661
finger563 merged 1 commit into
mainfrom
doc/cleanup

Conversation

@finger563

Copy link
Copy Markdown
Contributor

Description

The docs had grown organically into a flat doc/en/ directory where ~23
category folders (imu/, display/, network/, …) coexisted with ~53
individual component pages dumped at the top level, and the master index.rst
interleaved both in one ~80-entry toctree. This reorganizes the documentation
around a consistent, discoverable structure without changing any component
content.

Navigation — the master index.rst is 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:

  • Moved the ~53 flat component pages (and their _example.md companions) into
    category folders via git mv (history preserved): new core/, storage/,
    buses/, leds/, motor_control/, data/, protocols/; folded input
    devices into input/ and color into math/.
  • New dev_boards/ section collecting all 19 board-support packages, grouped
    by vendor (Espressif, Adafruit, LilyGo, M5Stack, MotorGo, Seeed, Waveshare,
    Other) — previously these were scattered through the flat top-level list.
  • Added a Getting Started page (getting_started.rst) surfacing the
    install/usage info that previously only lived in the repo README.
  • Added per-section index.rst landing pages and cross-links between related
    areas (LEDs↔led_driver, Motor Control↔bldc↔filters, MotorGo boards↔motor
    control, Math↔filters, Protocols↔network).

Component manifests:

  • Updated the documentation: URL in 57 idf_component.yml files to the new doc
    paths (e.g. spi.htmlbuses/spi.html, button.htmlinput/button.html,
    board pages → dev_boards/<vendor>/…), including the shared logger page
    anchors used by the logger, format, and binary-log components.

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?

  • Programmatically verified the new toctree structure: all 287 doc pages are
    reachable from index.rst, with no orphaned pages and no broken toctree
    references
    , and all RST title underlines are valid.
  • Verified moves don't break references: esp_docs include-build-file:: inc/…
    resolves from a fixed build root (not file-relative), \snippet uses Doxygen
    example IDs, and each .rst moved together with its _example.md so
    document-relative toctrees stay valid.
  • Verified all 116 active documentation: links across the component manifests
    resolve to real pages on disk (116 valid, 0 broken).
  • Built the documentation locally (./build_docs.sh) and visually reviewed the
    rendered navigation.

Screenshots (if appropriate):

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • Documentation Update

Checklist:

  • My change requires a change to the documentation.
  • I have updated the documentation accordingly.
  • All new and existing tests passed.
  • My code follows the code style of this project.

@github-actions

Copy link
Copy Markdown

✅Static analysis result - no issues found! ✅

@finger563 finger563 self-assigned this Jun 30, 2026
@finger563 finger563 merged commit bd5b257 into main Jun 30, 2026
10 checks passed
@finger563 finger563 deleted the doc/cleanup branch June 30, 2026 13:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant