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.

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