Survey: improving the Python std lib docs
Steve D'Aprano
steve+python at pearwood.info
Fri May 12 06:02:42 EDT 2017
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.
More information about the Python-list
mailing list