Survey: improving the Python std lib docs

[Chris Angelico]

On Sat, May 13, 2017 at 4:05 AM,  <jladasky at itu.edu> wrote:
> On Friday, May 12, 2017 at 3:02:58 AM UTC-7, Steve D'Aprano wrote:
>
>> (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...
>
> I agree with this suggestion.  I usually know what I want out of a module, but I don't know the exact name(s) of the relevant function(s).  Frequently, I find myself looking through the docs... and in parallel, I start a Python interpreter, type "import foo", and then "dir(foo)" to see everything that the module foo contains.
>

While I don't disagree with the docs suggestion, it's worth noting
that dir(foo) is a powerful feature, and part of what makes Python so
awesome. So don't be afraid to use it :)

TBH I'm +0.5 on the table; if it includes absolutely everything the
module offers, it'll be unworkably large on some modules, but if it
doesn't, how do you pick which are the "important" ones? Possibly this
is the right solution for most modules, but there'll be a few special
cases (eg argparse) that prefix it with "hey, check out this quick
start guide first".

ChrisA