Skip to content

docs(reference): appendix I, the optional extras - #203

Merged
kfox merged 1 commit into
mainfrom
docs/reference-extras-appendix
Aug 3, 2026
Merged

docs(reference): appendix I, the optional extras#203
kfox merged 1 commit into
mainfrom
docs/reference-extras-appendix

Conversation

@kfox

@kfox kfox commented Aug 3, 2026

Copy link
Copy Markdown
Owner

PR 4 of 8 in the reference-guide review follow-through. Stacked on #202 (merged), so this branches off main. Docs plus one real --doctor fix; no hardware.

What changes

The source of truth was wrong first. doctor._EXTRAS is already the name → module → what-it-unlocks table --doctor probes with, and it was missing wled — eleven entries against twelve declared extras, with nothing holding the two lists together. So a missing zeroconf, the one thing standing between [wled].listen and a WLED app that can discover the virtual device, showed up as silence in the command whose whole job is to say what is missing. The entry is added, and tests/test_packaging_metadata.py now pins _EXTRAS's names to the key set of [project.optional-dependencies] minus all, reporting both directions of drift.

Appendix I — Optional Extras, generated, joining doctor._EXTRAS with tomllib-parsed pyproject.toml: the extra, the module that has to import, what it unlocks, and its requirement strings with their bounds. Read from the file rather than from installed metadata, so a checkout that was never installed still builds the book.

The one thing a table cannot carry is in prose above it: extras do not accumulate — c64cast[midi] installed over c64cast[video] leaves you with MIDI and no video — so the install worth asking for is c64cast[all], or uv sync --all-extras from a checkout. That is the same reasoning doctor._probe_extras already prints as its hint.

The glossary becomes Appendix J (29-appendix-j-glossary.md), and the introduction gains a sentence pointing at I: the chapters have always named an extra where a feature needs one — video for a video scene, midi for a MIDI one, wled for the virtual device — and nothing collected them.

Bookkeeping: the new path in APPENDICES, the generated-file count 8 → 9 in tests/test_reference_appendices.py, and every "A to H" sentence — docs/reference/README.md and its source table, 01-introduction.md, Makefile, CLAUDE.md, README.md and the generator's own docstring. The "run this after changing…" lists gain or an install extra.

Verification

make lint                                                  # clean
make typecheck                                             # mypy --strict + pyright clean
make test                                                  # 3298 tests, OK
make reference-appendices && git diff --exit-code docs/    # no generated drift
make reference                                             # PDF renders
c64cast --doctor --skip-probe                              # EXTRAS now lists wled

Read the artefact too: the Appendix I opener page and its table render, and the contents page lists I Optional Extras and J Glossary at the right pages.

The extras are named piecemeal across five chapters and were never listed
anywhere, never with an install command. New generated Appendix I joins
doctor._EXTRAS with pyproject's [project.optional-dependencies]: what each
extra unlocks, the module --doctor imports, and the packages it installs.
The glossary becomes Appendix J.

doctor._EXTRAS was missing `wled`, so --doctor never reported a missing
zeroconf; test_packaging_metadata now pins its names to the declared extras.
@kfox
kfox merged commit 2ce17bd into main Aug 3, 2026
18 checks passed
@kfox
kfox deleted the docs/reference-extras-appendix branch August 3, 2026 22:41
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