Survey: improving the Python std lib docs

[Terry Reedy]

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