[Doc-SIG] Python docs in reST

Martin Blais martin.blais at gmail.com
Thu May 26 18:10:12 CEST 2005

On 5/26/05, Michael Foord <mike at pcblokes.com> wrote:
> Felix Wiemann wrote:
> >Martin Blais wrote:
> >
> >
> >
> >>1. why exactly do we want to change the documentation system?
> >>
> >>
> >
> >Ideas:
> >
> >* We want to have **well-readable** documentation source.

hmmm...  the current latex markup is as simple as it can be.  it's got
a word, and some form of delimiters, e.g. \function{foo}.  i don't
feel that `foo`:function: is all that much better.  the sectioning
uses markup (rest doesn't).  apart from that, there aren't many other
constructs that are difficult to read, are there?

> >* We want to get **flexibility** in that we can modify the parsed
> >  document using Python code.
> >
> >  In particular I have Docutils' document tree in mind -- use
> >  rst2pseudoxml.py to see what it looks like.  You can easily apply
> >  transformations on these trees, using your favorite programming
> >  language ;-).  This is not (easily?) possible with LaTeX.

yes, that is a good argument.

rest allows you to view the input files directly, as output (ascii
output = input).  this assumes that the markup is kept to its *bare
minimum*.  this is an *explicit* reason for creating rest in the first
place.  the more we are talking about adding markup on rest, the
stranger this whole discussion is becoming.  for example, if you're
trying to plug too much semantics on top of rest, and you add lots of
ugly markup, then you're kind-of breaking what rest is all about (and
to a certain extent this has already been happening with some of the
directives to docutils).  with rest, the source has to more or less
"look like" the output.  that's the whole point of rest.  this is not
a requirement for latex sources.

i see a contradiction: docutils is a toolchain with a parser that
extracts semantic (paragraphs, sections, etc.) from source documents
that have no markup (or very little).  it has been explicitly
discussed NOT to add too much visible markup on the docutils list, and
AFAIK it is an explicit goal of rest to keep the input syntax as
unobstrusive as possible.

and then, having too little markup does not allow us to do all the
things that we need to do for a proper documentation system.  we need
to mark functions, classes, bits of code, variables, argument,
optional arguments, etc.   to generate high quality docs with proper
indexes and good-looking output, you *really* need those things. 
there is no compromise about that, we need to be able to tell the doc
system what is what, and that requires some form of [ugly] markup.

therefore, there is the possibility that rest could never be used to
generate the kind of document that we need to generate, due to
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.

maybe we have to recognize that rest has its limits, and rest
recognizes the limits of its own domain, there are some places it
doesn't want to go.  it is fine for certain types of documents, but
not for others.  IMHO the worst thing that could happen is that one
day I open a text file supposedly writtne in rest, and that i can't
understand it because i have to learn what all that new markup is all

my point is: attempting to make rest jump through hoops to make it do
all the stuff that latex does is likely to break the beauty of rest. 
that would suck.

> >* We want an **easy-to-use** documentation system.  Any documentation
> >  should be renderable by typing "sometool.py input.txt output.html".
> >  Getting multi-document output should be similarly easy.

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

> As a side issue - it would be nice for developers of other
> modules/projects to be able to *easily* generate documentation that is
> consistent with the (IMO) nice looking Python documentation.
> I confess to *not* having looked into Latex markup [#]_ - so  I haven't
> a clue how difficult it is to use, but I love reST. If Latex is *that*
> easy to use why bother creating reST ;-)

(it really isn't all that much harder than rest.)

> In order to achieve this (becoming a useful documentation system for
> Python projects) - docutils needs to be capable of handling anything
> that is in the Python docs. So it is certainly in the interests of the
> docutils project to address these issues... whether that means it should

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

> be adopted as *the* method of documenting Python is another matter.
> Hopefully natural selection will start to work...
> 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.
> Hmmm..... I might even implement something like that myself.

while you're at it, can you implement output in the latex style as well? 
i'm getting the feeling that this would help as a long term measure.

to summarize all these discussions, there have been 3 separate threads:

1. splitting the docs system into a separate package (make it easier to reuse);
2. combining information from the source code with information in the
document sources;
3. converting sources to another system (some people think latex is
too difficult);


More information about the Doc-SIG mailing list