Documentation build overview

📚 cpython-previews | 🛠️ Build #32840146 | 📁 Comparing e9b96cd against main (c714b56)

  🔍 Preview build  

But move that warning below (L75 in your PR) where we mention HTTP server. pydoc can be used in the CLI

I'll disagree here, the introductory paragraph introduces that it can "served to a web browser," and there is no section specifically for the HTTP server. I'd generally prefer to put warnings in visible places (i.e., at the top of sections).

Seems reasonable to me! I don't have an opinion on placement.

there is no section specifically for the HTTP server

The paragraph serves a section for me. It has sufficient information about the port as well:

You can also use :program:pydoc to start an HTTP server on the local machine
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: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.

The fact that it serves localhost is important as well. So I would prefer having it there. Serving to a web browser has nothing to do with the HTTP server itself. You can serve to a webbrowser using other means. What's vulnerable is the HTTP server itself.

Note that someone wanting to know about the HTTP server itself may have Google jump to that sentence in the paragraph specifically. And having the warning closer is better. Especially if we use the words "especially useful".