Home Original page

[Python-Dev] Best practice for documentation for std lib

Nick Coghlan ncoghlan at gmail.com
Sun Sep 22 16:25:52 CEST 2013 
On 23 September 2013 00:16, Eli Bendersky <eliben at gmail.com> wrote:
> That's a good point. I would still posit that HTML documentation gets by far
> the most use, but docstrings are definitely important too. One more point in
> favor of either:
>
> 1. Maintaining both, as tiresome as it is (we try to do this, not always
> successfully, for all stdlib modules).
> 2. autodoc

FWIW, I've generally found *tactical* use of autodoc (i.e. function
and method level usage for cases where the docstrings and prose docs
*were* the same) to be quite effective. Then if there later proved to
value in splitting them for a given case, that's what I would do. It
isn't an all-or-nothing decision.

As Georg noted, we'd have to do some fancy footwork to make sure
autodoc didn't pick up the wrong module versions for the standard
library docs, though.

Cheers,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia
More information about the Python-Dev mailing list