<p dir="ltr"><br>
On 20 May 2013 08:51, "Demian Brecht" <<a href="mailto:demianbrecht@gmail.com">demianbrecht@gmail.com</a>> wrote:<br>
><br>
> @benjamin: Ah, i see. I wasn't around pre-Sphinx. However, unless<br>
> there's some custom build steps that I'm unaware of that may prevent<br>
> it, it should still be relatively easy to maintain the desired<br>
> narrative structure as long as the inline API docs are kept terse.</p>
<p dir="ltr">That's what docstrings are for - abbreviated docs for use when reading the code and at the interactive prompt.</p>
<p dir="ltr">The prose docs are designed to be a more discursive introduction to the full details of each operation, whereas docstrings are usually written more to provide someone that already knows what the function does with a reminder of the details.</p>

<p dir="ltr">Cheers,<br>
Nick.</p>
<p dir="ltr">><br>
> @antoine: Sorry, I may not have been clear. I wasn't advocating the<br>
> inclusion of the /entire/ doc pages inline. I'm advocating terse<br>
> documentation for the stdlib APIs and parameters. Narrative<br>
> documentation can (and should be) maintained externally, but could use<br>
> autodoc to include the terse references when desired. This would<br>
> ensure that the same docs are available (and consistent) when reading<br>
> the documentation as well as when neck-deep in code.<br>
><br>
> On Sun, May 19, 2013 at 3:32 PM, Antoine Pitrou <<a href="mailto:solipsis@pitrou.net">solipsis@pitrou.net</a>> wrote:<br>
> > On Sun, 19 May 2013 15:29:37 -0700<br>
> > Demian Brecht <<a href="mailto:demianbrecht@gmail.com">demianbrecht@gmail.com</a>> wrote:<br>
> >> This is more out of curiosity than to spark change (although I<br>
> >> wouldn't argue against it): Does anyone know why it was decided to<br>
> >> document external to source files rather than inline?<br>
> >><br>
> >> When rapidly digging through source, it would be much more helpful to<br>
> >> see parameter docs than to either have to find source lines (that can<br>
> >> easily be missed) to figure out the intention. Case in point, I've<br>
> >> been digging through cookiejar.py and request.py to figure out their<br>
> >> interactions. When reading through build_opener, it took me a few<br>
> >> minutes to figure out that each element of *handlers can be either an<br>
> >> instance /or/ a class definition (I was looking at how to define a<br>
> >> custom cookiejar for an HTTPCookieProcessor). Yes, I'm (now) aware<br>
> >> that there's some documentation at the top of request.py, but it would<br>
> >> have been helpful to have it right in the definition of build_opener.<br>
> >><br>
> >> It seems like external docs is standard throughout the stdlib. Is<br>
> >> there an actual reason for this?<br>
> ><br>
> > Have you seen the length of the documentation pages? Putting them<br>
> > inline in the stdlib module would make the code much harder to skim<br>
> > through.<br>
> ><br>
> > Regards<br>
> ><br>
> > Antoine.<br>
> ><br>
> ><br>
> > _______________________________________________<br>
> > Python-Dev mailing list<br>
> > <a href="mailto:Python-Dev@python.org">Python-Dev@python.org</a><br>
> > <a href="http://mail.python.org/mailman/listinfo/python-dev">http://mail.python.org/mailman/listinfo/python-dev</a><br>
> > Unsubscribe: <a href="http://mail.python.org/mailman/options/python-dev/demianbrecht%40gmail.com">http://mail.python.org/mailman/options/python-dev/demianbrecht%40gmail.com</a><br>
><br>
><br>
><br>
> --<br>
> Demian Brecht<br>
> <a href="http://demianbrecht.github.com">http://demianbrecht.github.com</a><br>
> _______________________________________________<br>
> Python-Dev mailing list<br>
> <a href="mailto:Python-Dev@python.org">Python-Dev@python.org</a><br>
> <a href="http://mail.python.org/mailman/listinfo/python-dev">http://mail.python.org/mailman/listinfo/python-dev</a><br>
> Unsubscribe: <a href="http://mail.python.org/mailman/options/python-dev/ncoghlan%40gmail.com">http://mail.python.org/mailman/options/python-dev/ncoghlan%40gmail.com</a><br>
</p>