[Doc-SIG] epydoc 1.0 release

[Edward Loper]

I just released version 1.0 of epydoc.  Epydoc is a tool for generating
API documentation for Python modules, based on their docstrings.

     <http://epydoc.sourceforge.net/>

It uses a markup language that is similar in some ways to reST, but
simpler (and I would say cleaner :) ).  It produces output similar to
javadoc; for an example of its output, see the API documentation for
epydoc itself:

     <http://epydoc.sourceforge.net/api/epydoc.html>

For a more extensive example (and a different stylesheet), see the API
documentation for NLTK (the natural language toolkit):

     <http://nltk.sourceforge.net/ref/nltk.html>

Epydoc is now fairly mature, and I don't plan to do much more work on
it in the near future.  But if/when docutils becomes The Standard
Framework for docstring tools, I will look into integrating epydoc into
the docutils framework (as a reader/parser and a writer/formatter).
I've been pretty happy with epydoc's markup langauge (epytext), and
hopefully if it gets integrated with docutils, other people will find
it useful too.

Below is a description of how the epytext markup language relates to
reST (the current standard markup language for docutils), for anyone
who's interested.  If you're interested in the epytext markup language
itself, but don't care how it relates to reST, then see the epytext
manual <http://epydoc.sourceforge.net/epytext.html>.  If you're not
interested at all, then go read the rest of your email. :)

-Edward

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
First of all, let me note that epytext and reST have very different
goals: reST is a very general-purpose markup language, that is good
for PEPs, webpages, etc.  Epytext is intended only for API
documentation generation.

Both epytext and reST markup can be divided into "block structure"
(paragraphs, lists, etc) and "inline markup" (italics, hyperlinks,
etc).  I'll discuss them separately.

Block structure
===============
   Epytext's block structure is basically a "light" version of reST,
   that's somewhat less leniant (e.g., underline length must match
   heading length).  In particular, it supports the following block
   structure constructs using basically the same syntax that reST
   uses:

       - paragraphs
       - unordered lists (bullet must be "-")
       - ordered lists (bullets must match "(\d+[.])+", like "12." or
         "3.2.")
       - literal blocks
       - doctest blocks
       - sections (underlines only, heading underline characters
         restricted to '=', '-', and '~'.)

   It also defines "field lists," which are like reST field lists,
   but have a different syntax -- bullets have the form "@\w+:" or
   "@\w+ \w+:", like "@return:" or "@param x:"

Inline markup
=============
   Epytext inline markup is fairly different from reST inline markup.
   All epytext inline markup has the form "x{...}", where "x" is a
   single capital letter.  This makes markup easy to spot, and makes
   nesting obvious.

   A matching pair of curly braces is only interpreted as inline markup
   if the left brace is immediately preceeded by a capital letter.  So
   in most cases, you can use curly braces in your text without any
   form of escaping.  However, you do need to escape curly braces when:

       - You want to include a single (un-matched) curly brace.
       - You want to preceed a matched pair of curly braces with a
         capital letter.

   I grepped through a pretty large number of docstrings, and both of
   these cases seem pretty rare.  Note that there is no valid Python
   expression where a pair of matched curly braces is immediately
   preceeded by a capital letter (except within string literals).  In
   particular, you never need to escape braces when writing Python
   dictionaries.

   I think that reST uses too many different inline markup constructs,
   that can interact with each other in weird and non-intuitive ways.
   A couple of them may have some value as "intuitive".  In particular,
   *emphasis* is widely used (though it's not obvious to me whether
   that should be bold or italics).  But constructs like ``this`` and
   #this# and `this`_ seem significantly less obvious to me.  I prefer
   a single unified inline markup syntax, that almost never requires
   any escaping.

For a more detailed description of the epytext markup language, see
the epytext manual on the epydoc homepage:

     <http://epydoc.sourceforge.net/epytext.html>