On 20 May 2013 08:51, "Demian Brecht" <demianbre...@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 <solip...@pitrou.net> wrote: > > On Sun, 19 May 2013 15:29:37 -0700 > > Demian Brecht <demianbre...@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@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@python.org > http://mail.python.org/mailman/listinfo/python-dev > Unsubscribe: http://mail.python.org/mailman/options/python-dev/ncoghlan%40gmail.com
_______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
