docs(reference): appendix I, the optional extras - #203
Merged
Conversation
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.
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.
PR 4 of 8 in the reference-guide review follow-through. Stacked on #202 (merged), so this branches off
main. Docs plus one real--doctorfix; no hardware.What changes
The source of truth was wrong first.
doctor._EXTRASis already the name → module → what-it-unlocks table--doctorprobes with, and it was missingwled— eleven entries against twelve declared extras, with nothing holding the two lists together. So a missingzeroconf, the one thing standing between[wled].listenand 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, andtests/test_packaging_metadata.pynow pins_EXTRAS's names to the key set of[project.optional-dependencies]minusall, reporting both directions of drift.Appendix I — Optional Extras, generated, joining
doctor._EXTRASwithtomllib-parsedpyproject.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 overc64cast[video]leaves you with MIDI and no video — so the install worth asking for isc64cast[all], oruv sync --all-extrasfrom a checkout. That is the same reasoningdoctor._probe_extrasalready 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 —videofor a video scene,midifor a MIDI one,wledfor the virtual device — and nothing collected them.Bookkeeping: the new path in
APPENDICES, the generated-file count 8 → 9 intests/test_reference_appendices.py, and every "A to H" sentence —docs/reference/README.mdand its source table,01-introduction.md,Makefile,CLAUDE.md,README.mdand the generator's own docstring. The "run this after changing…" lists gain or an install extra.Verification
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.