[Python-Dev] Best practice for documentation for std lib (original) (raw)

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