Use .. program:: and .. option:: directives for modules with a documented CLI

[picnixz]

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

[tomasr8]

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.

[picnixz]

Yes, and cmdoption is actually deprecated so it's better to use option :)

[Mr-Sunglasses]

@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.

[picnixz]

Except for venv where we may not want to do this, and for http.server which is the reason why I initially created this issue, I don't think we need to do more.

Exposing more CLIs likely requires a separate feature request for each module and deciding the fate of each existing CLI option such as those for self-testing should be tracked separately as well. So, once we're done with http.server and once we are done with venv as well, we will close this issue.

As such I'll remove the easy label as there is no "new" task apart from the ongoing ones.

[donBarbos]

@picnixz

Exposing more CLIs likely requires a separate feature request for each module and deciding the fate of each existing CLI option such as those for self-testing should be tracked separately as well. So, once we're done with http.server and once we are done with venv as well, we will close this issue.

everything is fine but I thought that doctest doesn't have a description of the CLI as a separate section at all.
it seems to be documented in detail but the information about the flags is scattered across different parts of the page.

maybe we could accept these changes :-)

[sobolevn]

@donBarbos yes, sounds nice! Thanks!

[donBarbos]

if we decide to update some cli docs why not link to their anchors in https://docs.python.org/dev/library/cmdline.html (instead of * :mod:`doctest` use * :ref:`doctest <doctest-cli>` )

[picnixz]

We can do it once we're done with the modules. And yes documenting doctest like that is a good idea.