[Python-Dev] Why is documentation not inline?

[Nick Coghlan]

On 20 May 2013 08:51, "Demian Brecht" <demianbrecht at gmail.com> wrote:
>
> @benjamin: Ah, i see. I wasn't around pre-Sphinx. However, unless
> there's some custom build steps that I'm unaware of that may prevent
> it, it should still be relatively easy to maintain the desired
> narrative structure as long as the inline API docs are kept terse.

That's what docstrings are for - abbreviated docs for use when reading the
code and at the interactive prompt.

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.

Cheers,
Nick.

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