gh-100583: Improving the pydoc doc
#100590
Conversation
|
Thanks. You need to change all occurences of this command. Also we usually dont write |
Thanks I'll do it |
|
I wonder if being so explicit would instead be a bit too noisy, especially with it being bolded. Here's the preview for reference. Maybe the first instance of the command can be (for example) the full |
|
or I was thinking to mention once |
Doc/library/pydoc.rst
Outdated
| at a shell prompt will display documentation on the :mod:`sys` module, in a | ||
| style similar to the manual pages shown by the Unix :program:`man` command. The | ||
| argument to :program:`pydoc` can be the name of a function, module, or package, | ||
| argument to :program:`<python> -m pydoc` can be the name of a function, module, or package, | ||
| or a dotted reference to a class, method, or function within a module or module | ||
| in a package. If the argument to :program:`pydoc` looks like a path (that is, | ||
| in a package. If the argument to :program:`<python> -m pydoc` looks like a path (that is, | ||
| it contains the path separator for your operating system, such as a slash in | ||
| Unix), and refers to an existing Python source file, then documentation is |
There was a problem hiding this comment.
I don't think these need changing. Please revert the changes.
Doc/library/pydoc.rst
Outdated
| When printing output to the console, :program:`pydoc` attempts to paginate the | ||
| When printing output to the console, :program:`<python> -m pydoc` attempts to paginate the | ||
| output for easier reading. If the :envvar:`PAGER` environment variable is set, | ||
| :program:`pydoc` will use its value as a pagination program. | ||
| :program:`<python> -m pydoc` will use its value as a pagination program. |
There was a problem hiding this comment.
Please revert these changes too. These are not command examples.
Doc/library/pydoc.rst
Outdated
| When :program:`<python> -m pydoc` generates documentation, it uses the current environment | ||
| and path to locate modules. Thus, invoking :program:`<python> -m pydoc spam` |
There was a problem hiding this comment.
These don't need changing. Please revert the changes.
Doc/library/pydoc.rst
Outdated
| You can also use :program:`pydoc` to start an HTTP server on the local machine | ||
| that will serve documentation to visiting web browsers. :program:`pydoc -p 1234` | ||
| that will serve documentation to visiting web browsers. :program:`<python> -m pydoc -p 1234` | ||
| will start a HTTP server on port 1234, allowing you to browse the | ||
| documentation at ``http://localhost:1234/`` in your preferred web browser. | ||
| Specifying ``0`` as the port number will select an arbitrary unused port. | ||
|
|
||
| :program:`pydoc -n <hostname>` will start the server listening at the given | ||
| :program:`<python> -m pydoc -n <hostname>` will start the server listening at the given | ||
| hostname. By default the hostname is 'localhost' but if you want the server to | ||
| be reached from other machines, you may want to change the host name that the | ||
| server responds to. During development this is especially useful if you want | ||
| to run pydoc from within a container. | ||
|
|
||
| :program:`pydoc -b` will start the server and additionally open a web | ||
| :program:`<python> -m pydoc -b` will start the server and additionally open a web |
There was a problem hiding this comment.
I think we can keep these.
There was a problem hiding this comment.
Great! You can click "resolve conversation" after you feel that the review comment has been addressed.
Doc/library/pydoc.rst
Outdated
| @@ -65,18 +65,18 @@ manner similar to the Unix :program:`man` command. The synopsis line of a | |||
| module is the first line of its documentation string. | |||
|
|
|||
| You can also use :program:`pydoc` to start an HTTP server on the local machine | |||
| that will serve documentation to visiting web browsers. :program:`pydoc -p 1234` | |||
| that will serve documentation to visiting web browsers. :program:`python -m pydoc -p 1234` | |||
There was a problem hiding this comment.
Please leave the leading space alone. reStructuredText allows for one or two spaces after a period.
|
We never used |
|
Thanks @ramvikrams for the PR, and @kumaraditya303 for merging it 🌮🎉.. I'm working now to backport this PR to: 3.11. |
(cherry picked from commit 7223d50) Co-authored-by: ram vikram singh <ramvikrams243@gmail.com>
|
GH-100606 is a backport of this pull request to the 3.11 branch. |
|
Thanks! |
(cherry picked from commit 7223d50) Co-authored-by: ram vikram singh <ramvikrams243@gmail.com>
|
Thanks @ramvikrams for the PR, and @kumaraditya303 for merging it 🌮🎉.. I'm working now to backport this PR to: 3.10. |
|
Too late now for this PR, but just FYI, the Also, since the 3.10 branch is equivalently active to the 3.11 branch in bugfix mode, and the problem reported against both branches, I'm not sure why it wasn't marked for backport against both—for docs changes, backporting things incompletely makes it more likely to hit merge conflicts on future backports, so AFAIK we generally try to backport to all bugfix branches to which the change is applicable. |
(cherry picked from commit 7223d50) Co-authored-by: ram vikram singh <ramvikrams243@gmail.com>
|
GH-100607 is a backport of this pull request to the 3.10 branch. |
gh-100583: changed the doc for calling pydoc my making it platform agnostic