Uh oh!
There was an error while loading.Please reload this page.
- Notifications
You must be signed in to change notification settings - Fork32k
Description
This is something (#129607 (comment)) I thought of when reviewing#129607. It's usually fine not to have links, but once we begin adding new command-line options to specific modules (e.g.,http.server), I think it'd be nice to be able to reference them using Sphinx.
Using the.. program:: directive also improves readability. For instance, comparehttps://docs.python.org/3/library/dis.html#command-line-interface withhttps://docs.python.org/3/library/http.server.html where the CLI documentation is at the end of the page, without even a dedicated section.
I suggest going through the modules in#109435 and select those whose documentation page can be improved. By looking at the list, I found the following that can be improved:
- https://docs.python.org/dev/library/ensurepip.html#command-line-interface (gh-130253)
- https://docs.python.org/dev/library/idle.html#command-line-usage (gh-130278)
- https://docs.python.org/3/library/pdb.html (roughly at 10% of the page)
- https://docs.python.org/dev/library/profile.html#instant-user-s-manual (roughly at 20% of the page) (gh-130314)
- https://docs.python.org/dev/library/venv.html#creating-virtual-environments (gh-130699)
- https://docs.python.org/3.14/library/webbrowser.html (section beforehttps://docs.python.org/3.14/library/webbrowser.html#webbrowser.Error)
quopri is both missing a documentation for its CLI so we can also add it.base64 as well, but I think it's meant to be undocumented. More modules can be found in#93096 as well.
For now, I suggest focusing on only those who already have a documented command-line interface and just improving them. Whether a module should have itsmain() function documented or not is out-of-scope for this issue.
Important
For those who want to work on the issue, please:
- Readhttps://devguide.python.org/getting-started/pull-request-lifecycle/ before anything else.
- Readhttps://www.sphinx-doc.org/en/master/usage/domains/standard.html#directive-program to understand how to use the
programdirective. - Selectone module for which the documentation will be improved. It's easier to review and backport.
- Open a pull request with the following title:
gh-130160: use `.. program::` directive for documenting `MODULE_NAME` CLI
Linked PRs
- gh-130160: use
.. program::directive for documentingensurepipCLI #130253 - [3.12] gh-130160: use
.. program::directive for documentingensurepipCLI (gh-130253) #130258 - [3.13] gh-130160: use
.. program::directive for documentingensurepipCLI (gh-130253) #130259 - gh-130160: use
optioninstead ofcmdoptionindis.rst#130255 - [3.13] gh-130160: use
optioninstead ofcmdoptionindis.rst(GH-130255) #130264 - [3.12] gh-130160: use
optioninstead ofcmdoptionindis.rst(GH-130255) #130265 - gh-130160: use
.. program::directive for documentingidleCLI #130278 - gh-130160: use
.. program::directive for documentingcProfileCLI #130314 - [3.13] gh-130160: use
.. program::directive for documentingidleCLI (GH-130278) #130494 - [3.12] gh-130160: use
.. program::directive for documentingidleCLI (GH-130278) #130495 - gh-130160: Convert
webbrowserdocs to use.. optiondirective #130497 (closed to allow newcomers to pick it up) - gh-130160: use
.. program::directive for documentingvenvCLI #130699 - [3.13] gh-130160: use
.. program::directive for documentingcProfileCLI (GH-130314) #130745 - [3.12] gh-130160: use
.. program::directive for documentingcProfileCLI (GH-130314) #130746 - gh-130160: use
.. program::directive for documentingwebbrowserCLI #130995 - gh-130160: use
.. program::directive for documentingpdbCLI #130996 - [3.13] gh-130160: use
.. program::directive for documentingwebbrowserCLI (GH-130995) #131003 - [3.12] gh-130160: use
.. program::directive for documentingwebbrowserCLI (GH-130995) #131004 - gh-130160: use
.. program::directive for documentinghttp.serverCLI #131010 - [3.12] gh-130160: use
.. program::directive for documentingpdbCLI (GH-130996) #131013 - [3.13] gh-130160: use
.. program::directive for documentingpdbCLI (GH-130996) #131014 - gh-130160: use
.. program::directive for documentingdoctestCLI #131034 - [3.13] gh-130160: use
.. program::directive for documentinghttp.serverCLI (GH-131010) #131293 - [3.12] gh-130160: use
.. program::directive for documentinghttp.serverCLI (GH-131010) #131294 - [3.13] gh-130160: use
.. program::directive for documentingdoctestCLI (GH-131034) #131320 - [3.12] gh-130160: use
.. program::directive for documentingdoctestCLI (GH-131034) #131321 - gh-130160: Add anchors to CLI Usage section for
cmdline#133182 - gh-130160: use
.. program::directive for documentingplatformCLI #133335 - [3.13] gh-130160: use
.. program::directive for documentingplatformCLI (GH-133335) #133341
Metadata
Metadata
Assignees
Projects
Status