[Doc-SIG] Python standard library documentation flavors

[Julien Palard]

Hi Eric,

> I am trying to understand the relationship between the Python standard library docstrings and the online documentation.

Both are documentation is probably the only relationship.

> For example, it does not appear that https://raw.githubusercontent.com/python/cpython/master/Doc/library/collections.rst is a strict superset of the docstrings in https://github.com/python/cpython/blob/master/Lib/collections/__init__.py

That's right.

> and I do not see any indication that docstrings are automatically extracted anywhere, nor any comment as to why or why not.
> Is there a standing decision *not* to use, say, sphinx-apidoc or sphinx.ext.autodoc? If so, can you point me to an explanation of how the benefits of fully human-maintained documentation outweigh the convenience and consistency of automation?

They are not automatically extracted and we don't want to: docstrings are documenting things one by one without context, only local facts, see PEP 257: "Do that, returns that.".

Documentation in the other hand should be present an overview, provide jump tables, hyperlinks, contexts, examples, what to avoid, ... like: https://docs.python.org/3/library/asyncio.html does.


> In other words, is this an affirmative policy decision that other projects should be guided by, or an accident of history with a lesson to be learned?

I don't want to tell what other project should do and there may exist projects with successfull autogenerated documentation (maybe search around "literate programming", I bet they have nice examples). Anyway having an auto-generated documentation is probably better than no documentation.

Here, in cpython, docstrings are usefull to the reader in need of information about a single thing, locally (in an IDE tooltip or calling help() in the REPL) while documentation is usefull to learn and to understand how to use something.

> Is there a document that clarifies the role of the standard library docstrings, and what belongs there versus in cpython/Doc/library? Maybe there is a PEP I haven't noticed?

There's PEP 257, not much I heard of.

Bests,
-- 
Julien Palard
https://mdk.fr