[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
 > mkhowto.

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 
sense.

 > > 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

-- 
Fred L. Drake, Jr.   <fdrake at acm.org>


More information about the Doc-SIG mailing list