Repository navigation
Use .. program:: and .. option:: directives for modules with a documented CLI #130160
Description
Activity
Tangentially related, but the
dismodule uses thecmdoptiondirective (as opposed tooption) to document its CLI. We might want to switch tooptionfor consistency.Yes, and
cmdoptionis actually deprecated so it's better to useoption:)- added a commit that references this issue
on Feb 18, 2025 - added a commit that references this issue
on Feb 18, 2025 60 remaining items
- added a commit that references this issue
on Nov 17, 2025 - added a commit that references this issue
on Nov 17, 2025
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, compare https://docs.python.org/3/library/dis.html#command-line-interface with https://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:
quopriis both missing a documentation for its CLI so we can also add it.base64as 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 its
main()function documented or not is out-of-scope for this issue.Important
For those who want to work on the issue, please:
programdirective.gh-130160: use `.. program::` directive for documenting `MODULE_NAME` CLILinked PRs
.. program::directive for documentingensurepipCLI #130253.. program::directive for documentingensurepipCLI (gh-130253) #130258.. program::directive for documentingensurepipCLI (gh-130253) #130259optioninstead ofcmdoptionindis.rst#130255optioninstead ofcmdoptionindis.rst(GH-130255) #130264optioninstead ofcmdoptionindis.rst(GH-130255) #130265.. program::directive for documentingidleCLI #130278.. program::directive for documentingcProfileCLI #130314.. program::directive for documentingidleCLI (GH-130278) #130494.. program::directive for documentingidleCLI (GH-130278) #130495webbrowserdocs to use.. optiondirective #130497 (closed to allow newcomers to pick it up).. program::directive for documentingvenvCLI #130699.. program::directive for documentingcProfileCLI (GH-130314) #130745.. program::directive for documentingcProfileCLI (GH-130314) #130746.. program::directive for documentingwebbrowserCLI #130995.. program::directive for documentingpdbCLI #130996.. program::directive for documentingwebbrowserCLI (GH-130995) #131003.. program::directive for documentingwebbrowserCLI (GH-130995) #131004.. program::directive for documentinghttp.serverCLI #131010.. program::directive for documentingpdbCLI (GH-130996) #131013.. program::directive for documentingpdbCLI (GH-130996) #131014.. program::directive for documentingdoctestCLI #131034.. program::directive for documentinghttp.serverCLI (GH-131010) #131293.. program::directive for documentinghttp.serverCLI (GH-131010) #131294.. program::directive for documentingdoctestCLI (GH-131034) #131320.. program::directive for documentingdoctestCLI (GH-131034) #131321cmdline#133182.. program::directive for documentingplatformCLI #133335.. program::directive for documentingplatformCLI (GH-133335) #133341.. program::directive for documentingvenvCLI (GH-130699) #136550.. program::directive for documentingvenvCLI (GH-130699) #136551cmdline(GH-133182) #141664cmdline(GH-133182) #141667