On 5/12/2017 6:02 AM, Steve D'Aprano wrote:
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 only thing possibly 'new' here is 'each' versus 'selected'. 'Each'
could be seen as an aspiration. It could also be seen as a diversion
from making concrete improvements, one chapter at a time, by a
self-volunteer who will write and *commit to maintaining* such a table
for a particular module.
The docs for builtins starts with a table of built-in functions:
https://docs.python.org/3/library/functions.html
Table has names only, alphabetically. Maintenance will be collective.
https://docs.python.org/3/library/itertools.html#module-itertools
Categorized names, alphabetical within categories, with columns for
arguments, results, and examples. Raymond Hettinger maintains it.
> The statistics module shows something similar:
> https://docs.python.org/3/library/statistics.html
Categorized names with explanation, with a logical order within
categories that is copied in the details section. Steve will presumably
make sure the index is updated if anyone adds new functions.
Steve, did you get any opposition to including that table? Does the
abstract idea of 'more tables' need discussion?
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
I disagree. The alphabetical list mixes together 9 string constants,
defining subsets of ascii characters, and 3 callables (1 function and 2
classes). The doc *could* start with a short table
Contents
| string constants | define subsets of ascii characters |
| capwords | Capitalize each word in a string |
| Formatter | Custom formatting extending builtin format() |
| Template | Simple $-based string substitution |
But this listing of mostly unused *objects* misses the 99% meat of the
chapter, the definition format strings and format specs and the format()
examples. While this chapter originally documented the string module,
it now mostly documents format() strings. The doc for the string
functions which are now strings methods was moved elsewhere. (The
capwords function is a vestigial remnant that was not made a string
method.) There is already a sidebar Table of Contents, which is
generated automatically.
To me, the biggest deficiency of this chapter is the lack of any
Formatter examples. From a cursory reading, I have no idea how to use
it. I also question the placement of Formatter before the format() doc
it depends on.
A table I would like is one that replaces the wordy contents of the
'String constants' section, which should perhaps be renamed 'Character
categories'. I may have proposed this a decade ago and had the idea
rejected.
| digits | '0123456789'
...
| ascii_uppercase | 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
...
| printable | digits + ascii_letters + punctuation + whitespace |
There should then be an explanation or reference to how at access
similar unicode categories.
--
Conclusion: specific chapters need specific thought as to whether and
what type of table might be useful.
--
Terry Jan Reedy
--
https://mail.python.org/mailman/listinfo/python-list
