[Python-Dev] query: docstring formatting in python distutils code

[Georg Brandl]

Am 07.07.2010 21:11, schrieb Fred Drake:
> On Wed, Jul 7, 2010 at 2:27 PM, Georg Brandl <g.brandl at gmx.net> wrote:
>> I know, and this is what I originally intended for Sphinx.  However, the calls
>> for automatic doc generation are very loud, and it's understandable that most
>> project can't afford writing their documentation twice.
> 
> The ability to provide extended content beyond what's provided in the
> docstring using the auto* constructs may make it feasible to start
> avoiding some of those DRY violations for Python's standard library;
> I'm enjoying those for another project.
> 
> I hope we don't end up in a position where we can't use the auto*
> constructs in the Python documentation.

Let's say we were okay with giving up single-source docs, one potential
problem is that autodoc needs to import the modules in question, which
can become a problem, on one hand for platform-specific modules, on the
other because the Python building the docs is not necessarily the Python
that is documented.

Georg