Skip to content

Automatically generate CLI reference documentation via sphinx-click and a custom directive#355

Open
agriyakhetarpal wants to merge 7 commits into
mainfrom
sphinx-click-integration
Open

Automatically generate CLI reference documentation via sphinx-click and a custom directive#355
agriyakhetarpal wants to merge 7 commits into
mainfrom
sphinx-click-integration

Conversation

@agriyakhetarpal
Copy link
Copy Markdown
Member

@agriyakhetarpal agriyakhetarpal commented May 27, 2026

I noticed in #350 that our CLI reference page is likely to get outdated often, as we may forget to update it with new CLI flags and subcommands being added. This PR introduces an inline Sphinx extension with a directive that scans entry points added by pyodide-build in pyodide-cli and adds them to the page. See the PR preview: https://pyodide-build--355.org.readthedocs.build/en/355/reference/cli.html

We can also skip such automation if we want, but based on my experience writing customisations for the Sphinx build process, this will remain fairly stable and shouldn't break in the future. It also beats adding new commands manually, so I recommend keeping it :D

The extension doesn't support Sphinx 9 yet, as I noticed from this issue that I encountered: click-contrib/sphinx-click#159, which has a PR to fix it: click-contrib/sphinx-click#160. We don't need any cutting-edge features from Sphinx anyway and none of our extensions imposes a Sphinx >=9 bound, so we should be fine with 8.x. Also, the extension doesn't support Markdown, but that's easily workaroundable with {eval-rst}: click-contrib/sphinx-click#127.

Lastly, I dropped the requirements-doc.txt file, as it's kind of redundant with dependency groups now.

Copy link
Copy Markdown
Member

@ryanking13 ryanking13 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks! Would it be able to hide some of the subcommands from the generation? I intentionally not included build-recipes, build-recipes-no-deps, skeleton subcommands as I don't want to distract users with recipe-related commands. Most of the users who are looking at that document don't need to be aware of the recipe.

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.

2 participants