[Python-Dev] The docs, reloaded

Martin Blais blais at furius.ca
Wed May 23 02:30:17 CEST 2007

On 5/22/07, Martin Blais <blais at furius.ca> wrote:
> ReST works well only when there is little markup.  Writing code
> documentation generally requires a lot of markup, you want to make
> variables, classes, functions, parameters, constants, etc..  (A better
> avenue IMHO would be to augment docutils with some code to
> automatically figure out the syntax of functions, parameters, classes,
> etc., i.e., less markup, and if we do this in Python we may be able to
> use introspection.  This is a challenge, however, I don't know if it
> can be done at all.)

Just to follow-up on that idea: I don't think it would be very
difficult to write a very small modification to docutils that
interprets the default role with more "smarts", for example, you can
all guess what the types of these are about:

  `class Foo`  (this is a class Foo)
  `bar(a, b, c) -> str`  (this is a function "bar" which returns a string)
  `name (attribute)`  (this is an attribute)

...so why couldn't the computer solve that problem for you?  I'm sure
we could make it happen.  Essentially, what is missing from ReST is
"less markup for documenting programs".  By restricting the
problem-set to Python programs, we can go a long way towards making
much of this automatic, even without resorting to introspecting the
source code that is being documented.

More information about the Python-Dev mailing list