[Doc-SIG] Python docs in reST
Fred L. Drake, Jr.
fdrake at acm.org
Thu May 26 22:34:18 CEST 2005
On Thursday 26 May 2005 12:10, Martin Blais wrote:
> the sectioning
> uses markup (rest doesn't). apart from that, there aren't many other
> constructs that are difficult to read, are there?
Last I checked, ReST needed markup for sectioning as well, but had the
advantage that section level was implied by the concrete markup, not by
naming. This makes more sense in light of re-usable content components that
may appear at different section levels in different documents. (Yes, I do
consider heading underlines to be markup, no matter how reasonable!)
> self-imposed limitations. if you add lots of ugly markup to rest,
> you're creating something else, it's not rest anymore. bluntly
> stated, the goal of rest is NOT to have markup, and we need LOTS of
> markup. reconcile that.
This is another reason I'm not convinced we need to change markup systems.
> the more i hear this, the more i see great "value" in splitting the
> docs from the python source. it's 95% of the way there already with
There are a couple of aspects to this:
1. Splitting the documentation tools from the Python sources.
This is something that is specifically desirable now. There are a number
of other projects that use the LaTeX markup from Python; these are mostly
related to Python in some way. (These also create a reason to continue to
maintain the LaTeX markup.)
> i disagree... personally, i wish that docutils remains as simple as
> possible (that is the raison d'etre of it) if it means it has
> limitations, then fine by me. i really don't see why docutils
> "needs" to be capable of handling all that is in the python docs.
It certainly doesn't need to support it all out of the box, especially the
constructs specific to documenting Python (or other OO programming
languages). It would be nice to have the option of using it for documenting
at least Python packages of small to moderate size, with support from an
add-on library of text roles and directives.
> docutils needs to do what it does best: extract document structure
> from files with no markup (or very little). AFAIK it was never meant
> as a complete replacement for a document preparation system. it was
> created from the recognition by many different people at the same time
> that one could extract structure from simple text files.
Having a structure that supports the Python documentation is not a trivial
exercise, and I'm not sold that it needs to be done in ReST. I think there's
more value in being explicit than in being minimal, so it's questionable that
the goal of converting the "standard" Python documentation to ReST makes
> > Surely implementing a Python source reader (that works by introspection
> > or whatever) that extracts docstrings and inserts it *into* a reST
> > document (still a two pass process) would help as a short term measure.
It shouldn't be too hard to implement a specialized URL scheme that converts
an object reference to documentation text for some particular system.
Fred L. Drake, Jr. <fdrake at acm.org>
More information about the Doc-SIG