Repository navigation
docs: generate the module reference from the type stubs - #407
Merged
Merged
Conversation
# Conflicts: # src/audiograph/audiograph.pyi
…, shaper and mixer-voice text
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.
The Reference section is now written from the type stubs. Each module's names, constructors, options and constants on the Reference pages come from its
.pyi, so the docs and your editor's completion can't drift apart. This PR is stacked on #404 (the stubs) and targets its branch; retarget it to main once that merges.The existing pages keep their file names and headings, so every link to them still works, including the
#audiobiquadand#audioroutemidsideanchors. Their hand-written module sections are now generated, with the prose that a user needs moved into the stubs' docstrings (the constructor table for the biquad stays as a short hand-written table). Two new pages, Mixing and routing and Analysis and utilities, cover the modules that had no page, and the pump and Vorbis pages gain a generated names section. The docs had never been built with Sphinx here, so this also addsdocs/conf.py, a requirements file,.readthedocs.yamland a Docs workflow that builds with warnings as errors. Making that build pass meant pointing links to folders and files outsidedocs/at GitHub and fixing eight heading jumps in the upstream reports.I built the site with
sphinx-build -W --keep-goingwith and without network and it finishes with no warnings; all 25 modules render. I didn't build it on Read the Docs, and I haven't read every generated page for wording.