[Doc-SIG] Python standard library documentation flavors
julien at palard.fr
Mon Oct 14 17:25:29 EDT 2019
> 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
> 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.
More information about the Doc-SIG