Survey: improving the Python std lib docs

[Steve D'Aprano]

One of the more controversial aspects of the Python ecosystem is the Python
docs. Some people love them, and some people hate them and describe them as
horrible.

Here are a couple of suggestions for improving(?) the docs. What do you
think?

(They're not my ideas, the originated on Reddit.)


(1) Table of functions/classes at the start of each module doc

The docs for builtins starts with a table of built-in functions:

https://docs.python.org/3/library/functions.html


Docs for other modules should do similar, e.g. for the string module there
should be a table showing:

ascii_letters
ascii_lowercase
ascii_uppercase
capwords
digits
Formatter
hexdigits 
octdigits 
printable 
punctuation
Template
whitespace


which link to the detailed documentation for that object.

https://docs.python.org/3/library/string.html 


The statistics module shows something similar:

https://docs.python.org/3/library/statistics.html



(2) The PHP documentation allows you to search for a term by typing it into
the URL after the domain, e.g. to search for "split", go to:

http://php.net/split


If you try the same thing with the Python docs:

http://python.org/split

you get a 404. Suggestion: 404s should redirect and search the docs.




-- 
Steve
Emoji: a small, fuzzy, indistinct picture used to replace a clear and
perfectly comprehensible word.