Generate the Python SDK API reference as a native docs page - #94
Merged
Conversation
Add scripts/generate-python-reference.py, which walks the lightpanda package with pdoc's Python API and writes src/content/reference/python-api.mdx: one section per public class, method, property, function and exception, with the signatures and docstrings shipped in the code. Emitting MDX instead of pdoc's HTML keeps the page inside the Nextra site, so it gets the sidebar, Pagefind search, dark mode and stable deep links like every other page. Sync classes are listed in full; their Async twins list only what they add. A daily workflow regenerates the page from the lightpanda-python main branch (snake_case-only API, matching the hand-written docs) and opens a pull request when it changed; it also smoke-runs on pull requests that touch the generator. Seed the page from a local run, list it in the sidebar after the curated Python SDK page, point that page and the Python guide at it, and redirect /docs/python to it so the links in the package README resolve.
Contributor
|
Wouldn't it be better to to integrate the generated content in the "Python SDK" page instead of adding a new one and duplicate some of the content? |
Collaborator
Author
|
yes, I think we can just have one, I added as a separate one, just to compare |
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
2 participants
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.
Replaces the pdoc HTML approach from #92 with a generated MDX page,
src/content/reference/python-api.mdx, so the API reference renders like the rest of the docs: sidebar entry under "Python SDK", Pagefind search, dark mode, and stable deep links such as/reference/python-api#session-wait-for-selector.scripts/generate-python-reference.pywalks thelightpandapackage with pdoc's Python API and emits one section per public class, method, property, function and exception. Docstrings are converted from reST and escaped for MDX; sync classes are listed in full and theirAsync*twins list only what they add..github/workflows/python-reference.ymlregenerates the page daily from thelightpanda-pythonmain branch and opens a PR when it changed. It also smoke-runs on PRs that touch the generator./docs/pythonredirects to it so the links already in the package README resolve.Supersedes #93.
Follow-up in
lightpanda-python: retarget the two README links fromlightpanda.io/docs/python/tolightpanda.io/docs/reference/python-api, and the sentence saying the reference is regenerated from the PyPI package (it is now generated from main).