[Doc-SIG] Python standard library documentation flavors

[Eric Irrgang]

Hello,

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

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
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?

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?

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?

I hope my question is not too open-ended for this list, but I would also
welcome replies off list.

Thank you for your time,
Eric
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/doc-sig/attachments/20191009/a6485322/attachment.html>