René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Use `.. program::` and `.. option::` directives for modules with a documented CLI","articleBody":"This is something (https://github.com/python/cpython/pull/129607#discussion_r1957162894) 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.\n\nUsing 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.\n\nI suggest going through the modules in https://github.com/python/cpython/issues/109435 and select those whose documentation page can be improved. By looking at the list, I found the following that can be improved:\n\n- [x] https://docs.python.org/dev/library/ensurepip.html#command-line-interface ([gh-130253](https://github.com/python/cpython/pull/130253))\n- [x] https://docs.python.org/dev/library/idle.html#command-line-usage ([gh-130278](https://github.com/python/cpython/pull/130278))\n- [x] https://docs.python.org/3/library/pdb.html (roughly at 10% of the page)\n- [x] https://docs.python.org/dev/library/profile.html#instant-user-s-manual (roughly at 20% of the page) ([gh-130314](https://github.com/python/cpython/pull/130314))\n- [x] https://docs.python.org/dev/library/venv.html#creating-virtual-environments ([gh-130699](https://github.com/python/cpython/pull/130699))\n- [x] https://docs.python.org/3.14/library/webbrowser.html (section before https://docs.python.org/3.14/library/webbrowser.html#webbrowser.Error)\n\n`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 https://github.com/python/cpython/issues/93096 as well.\n\nFor 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.\n\n\u003e [!IMPORTANT]\n\u003e For those who want to work on the issue, please:\n\u003e\n\u003e - Read https://devguide.python.org/getting-started/pull-request-lifecycle/ before anything else.\n\u003e - Read https://www.sphinx-doc.org/en/master/usage/domains/standard.html#directive-program to understand how to use the `program` directive.\n\u003e - Select **one** module for which the documentation will be improved. It's easier to review and backport.\n\u003e - Open a pull request with the following title: \u003ccode\u003egh-130160: use \\`.. program::\\` directive for documenting \\`MODULE_NAME\\` CLI\u003c/code\u003e\n\n\u003c!-- gh-linked-prs --\u003e\n### Linked PRs\n* gh-130253\n* gh-130258\n* gh-130259\n* gh-130255\n* gh-130264\n* gh-130265\n* gh-130278\n* gh-130314\n* gh-130494\n* gh-130495\n* gh-130497 (closed to allow newcomers to pick it up)\n* gh-130699\n* gh-130745\n* gh-130746\n* gh-130995\n* gh-130996\n* gh-131003\n* gh-131004\n* gh-131010\n* gh-131013\n* gh-131014\n* gh-131034\n* gh-131293\n* gh-131294\n* gh-131320\n* gh-131321\n* gh-133182\n* gh-133335\n* gh-133341\n* gh-136550\n* gh-136551\n* gh-141664\n* gh-141667\n\u003c!-- /gh-linked-prs --\u003e\n","author":{"url":"https://github.com/picnixz","@type":"Person","name":"picnixz"},"datePublished":"2025-02-15T17:49:44.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":10},"url":"https://github.com/130160/cpython/issues/130160"}