Description

picnixz

opened on Feb 15, 2025

Issue body actions

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:

• 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 before https://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 its main() function documented or not is out-of-scope for this issue.

Important

For those who want to work on the issue, please:

• Read https://devguide.python.org/getting-started/pull-request-lifecycle/ before anything else.
• Read https://www.sphinx-doc.org/en/master/usage/domains/standard.html#directive-program to understand how to use the program directive.
• Select one 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 documenting ensurepip CLI #130253
• [3.12] gh-130160: use .. program:: directive for documenting ensurepip CLI (gh-130253) #130258
• [3.13] gh-130160: use .. program:: directive for documenting ensurepip CLI (gh-130253) #130259
• gh-130160: use option instead of cmdoption in dis.rst #130255
• [3.13] gh-130160: use option instead of cmdoption in dis.rst (GH-130255) #130264
• [3.12] gh-130160: use option instead of cmdoption in dis.rst (GH-130255) #130265
• gh-130160: use .. program:: directive for documenting idle CLI #130278
• gh-130160: use .. program:: directive for documenting cProfile CLI #130314
• [3.13] gh-130160: use .. program:: directive for documenting idle CLI (GH-130278) #130494
• [3.12] gh-130160: use .. program:: directive for documenting idle CLI (GH-130278) #130495
• gh-130160: Convert webbrowser docs to use .. option directive #130497 (closed to allow newcomers to pick it up)
• gh-130160: use .. program:: directive for documenting venv CLI #130699
• [3.13] gh-130160: use .. program:: directive for documenting cProfile CLI (GH-130314) #130745
• [3.12] gh-130160: use .. program:: directive for documenting cProfile CLI (GH-130314) #130746
• gh-130160: use .. program:: directive for documenting webbrowser CLI #130995
• gh-130160: use .. program:: directive for documenting pdb CLI #130996
• [3.13] gh-130160: use .. program:: directive for documenting webbrowser CLI (GH-130995) #131003
• [3.12] gh-130160: use .. program:: directive for documenting webbrowser CLI (GH-130995) #131004
• gh-130160: use .. program:: directive for documenting http.server CLI #131010
• [3.12] gh-130160: use .. program:: directive for documenting pdb CLI (GH-130996) #131013
• [3.13] gh-130160: use .. program:: directive for documenting pdb CLI (GH-130996) #131014
• gh-130160: use .. program:: directive for documenting doctest CLI #131034
• [3.13] gh-130160: use .. program:: directive for documenting http.server CLI (GH-131010) #131293
• [3.12] gh-130160: use .. program:: directive for documenting http.server CLI (GH-131010) #131294
• [3.13] gh-130160: use .. program:: directive for documenting doctest CLI (GH-131034) #131320
• [3.12] gh-130160: use .. program:: directive for documenting doctest CLI (GH-131034) #131321
• gh-130160: Add anchors to CLI Usage section for cmdline #133182
• gh-130160: use .. program:: directive for documenting platform CLI #133335
• [3.13] gh-130160: use .. program:: directive for documenting platform CLI (GH-133335) #133341
• [3.14] gh-130160: use .. program:: directive for documenting venv CLI (GH-130699) #136550
• [3.13] gh-130160: use .. program:: directive for documenting venv CLI (GH-130699) #136551
• [3.14] gh-130160: Add anchors to CLI Usage section for cmdline (GH-133182) #141664
• [3.13] gh-130160: Add anchors to CLI Usage section for cmdline (GH-133182) #141667

Activity

1. picnixz

   added

   docsDocumentation in the Doc dirDocumentation in the Doc dir

   on Feb 15, 2025
2. github-project-automation

   added this to docs issueson Feb 15, 2025
3. github-project-automation

   moved this to Todo in docs issueson Feb 15, 2025
4. picnixz

   added

   easy

   on Feb 15, 2025
5. tomasr8 commented on Feb 15, 2025

   

   tomasr8

   on Feb 15, 2025

   Member

   More actions

   Tangentially related, but the dis module uses the cmdoption directive (as opposed to option) to document its CLI. We might want to switch to option for consistency.
6. picnixz commented on Feb 15, 2025

   

   picnixz

   on Feb 15, 2025

   MemberAuthor

   More actions

   Yes, and cmdoption is actually deprecated so it's better to use option :)
7. Mr-Sunglasses

   added a commit that references this issue on Feb 18, 2025

   pythongh-130160: use `.. program::` directive for documenting `ensure…

   64ac23b
8. sobolevn

   added a commit that references this issue on Feb 18, 2025

   pythongh-130160: use `option` instead of `cmdoption` in `dis.rst`

   eb4c677
9. pfmoore

   closed this as completedin #130253on Feb 18, 2025
10. pfmoore

    added a commit that references this issue on Feb 18, 2025

    gh-130160: use `.. program::` directive for documenting `ensurepip` C…

    8cd7f8b
11. Mr-Sunglasses commented on Feb 18, 2025

    

    Mr-Sunglasses

    on Feb 18, 2025

    Contributor

    More actions

    @pfmoore , @sobolevn

    There are more files related that need to be changed that are mentioned in this issue, so it's good that we should reopen this until all those changes are encountered.
12. sobolevn

    reopened this on Feb 18, 2025
13. miss-islington

    added 2 commits that reference this issue on Feb 18, 2025

    pythongh-130160: use `.. program::` directive for documenting `ensure…

    45a3590

    pythongh-130160: use `.. program::` directive for documenting `ensure…

    d47bff3
14. pfmoore

    added a commit that references this issue on Feb 18, 2025

    [3.13] gh-130160: use `.. program::` directive for documenting `ensur…

    a273543
15. 60 remaining items
16. picnixz

    added 2 commits that reference this issue on Jul 11, 2025

    [3.14] gh-130160: use `.. program::` directive for documenting `venv`…

    e4e86a1

    [3.13] gh-130160: use `.. program::` directive for documenting `venv`…

    f7f1448
17. Pranjal095

    added 2 commits that reference this issue on Jul 12, 2025

    pythongh-130160: use `.. program::` directive for documenting `platfo…

    fb1cfbb

    pythongh-130160: use `.. program::` directive for documenting `venv` …

    0854abd
18. picnixz

    added a commit that references this issue on Jul 13, 2025

    pythongh-130160: use `.. program::` directive for documenting `venv` …

    5284515
19. taegyunkim

    added a commit that references this issue on Aug 4, 2025

    pythongh-130160: use `.. program::` directive for documenting `venv` …

    f0e5b81
20. Agent-Hellboy

    added a commit that references this issue on Aug 19, 2025

    pythongh-130160: use `.. program::` directive for documenting `venv` …

    416a065
21. kumaraditya303

    added a commit that references this issue on Sep 9, 2025

    [3.14] pythongh-130160: use `.. program::` directive for documenting …

    27f70d8
22. hugovk

    added a commit that references this issue on Nov 17, 2025

    gh-130160: Add anchors to CLI Usage section for `cmdline` (#133182)

    cc6b62a
23. miss-islington

    added a commit that references this issue on Nov 17, 2025

    pythongh-130160: Add anchors to CLI Usage section for `cmdline` (pyth…

    1664289
24. hugovk

    added a commit that references this issue on Nov 17, 2025

    [3.14] gh-130160: Add anchors to CLI Usage section for `cmdline` (GH-…

    cc315dc
25. donbarbos

    added a commit that references this issue on Nov 17, 2025

    [3.13] pythongh-130160: Add anchors to CLI Usage section for `cmdline` (

    1992d2b
26. hugovk

    added a commit that references this issue on Nov 17, 2025

    [3.13] gh-130160: Add anchors to CLI Usage section for `cmdline` (GH-…

    a63ceb7
27. hugovk

    closed this as completedon Nov 17, 2025
28. StanFromIreland

    added a commit that references this issue on Dec 6, 2025

    pythongh-130160: Add anchors to CLI Usage section for `cmdline` (pyth…

    da35baa

Issue actions