[Python-Dev] The docs, reloaded

[Georg Brandl]

Robert Kern schrieb:
> Neal Becker wrote:
> 
>> There is an effort as part of numpy to come up with a new system using
>> docstrings.  It seems to me it would be unfortunate if these two efforts
>> were not coordinated.
> 
> I don't think so. The issue with numpy is getting our act together and making
> parseable docstrings for auto-generated API documentation using existing tools
> or slightly modified versions thereof. No one is actually contemplating building
> a new tool. AFAICT, Georg's (excellent) work doesn't address that use.

Indeed, I don't intend to do anything about docstrings. IMO, docs automatically
generated from docstrings can work, but only if there's a single consistent
style applied, and the whole thing is written in a markup language, of course,
not text only.

This is not the case for the Python standard library, so converting it is not
an option; in any case, putting all information that is available in the docs
into the docstrings would make many modules much less readable.


> I don't
> think there is anything to coordinate, here. Provided that Georg's system
> doesn't place too many restrictions on the reST it handles, we could use the
> available reST math options if we wanted to use Georg's system.

Of course, for numpy math is much more of importance than for the core.
I'm sure the docutils developers will be supportive in case someone volunteers
to create/improve reST math capabilities.

cheers,
Georg