Python standard library documentation flavors

--===============4406502691983738119==
Content-Type: multipart/alternative; boundary="000000000000b6fd4c0594764643"

--000000000000b6fd4c0594764643
Content-Type: text/plain; charset="UTF-8"

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

--000000000000b6fd4c0594764643
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div dir=3D"ltr"><div dir=3D"ltr"><div dir=3D"ltr"><div dir=3D"ltr">Hello,<=
div><br></div><div>I am trying to understand the relationship=C2=A0between =
the Python standard library docstrings and the online documentation.</div><=
div><br></div><div>For example, it does not appear that=C2=A0<a href=3D"htt=
ps://raw.githubusercontent.com/python/cpython/master/Doc/library/collection=
s.rst">https://raw.githubusercontent.com/python/cpython/master/Doc/library/=
collections.rst</a> is a strict superset of the docstrings in <a href=3D"ht=
tps://github.com/python/cpython/blob/master/Lib/collections/__init__.py">ht=
tps://github.com/python/cpython/blob/master/Lib/collections/__init__.py</a>=
</div><div>and I do not see any indication that docstrings are automaticall=
y extracted anywhere, nor any comment as to why or why not.</div><div><br><=
/div><div>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 be=
nefits of fully human-maintained documentation outweigh the convenience and=
 consistency of automation?</div><div><br></div><div>In other words,=C2=A0i=
s this an affirmative policy decision that other projects should be guided =
by, or an accident of history with a lesson to be learned?</div><div><br></=
div><div>Is there a document that clarifies the role of the standard librar=
y docstrings, and what belongs there versus in cpython/Doc/library? Maybe t=
here is a PEP I haven&#39;t noticed?</div><div><br></div><div>I hope my que=
stion is not too open-ended for this list, but I would also welcome replies=
 off list.</div><div><br></div><div>Thank you for your time,</div><div>Eric=
</div></div></div></div></div>

--000000000000b6fd4c0594764643--

--===============4406502691983738119==
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: inline

_______________________________________________
Doc-SIG maillist  -  [email protected]
https://mail.python.org/mailman/listinfo/doc-sig

--===============4406502691983738119==--