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 _______________________________________________ Doc-SIG maillist - Doc-SIG@python.org https://mail.python.org/mailman/listinfo/doc-sig
