[Python-Dev] The docs, reloaded (original) (raw)

Georg Brandl g.brandl at gmx.net
Mon May 21 21:09:24 CEST 2007

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

More information about the Python-Dev mailing list