EpydocLaTeX

We've been using epydoc on our FiPy project for a couple of years and are very happy with it. The one area where we thought there was room for improvement was in separating the content from the LaTeX markup (I recall somebody expressing a similar desire re: HTML/CSS expressed at PyCon'04; we don't use HTML output (too much math), so I don't know where that side stands). We got this working well enough for our own needs about two years ago, but never cleaned it up enough to pass back. My reward for that lethargy is that I got to merge the changes from 2.1 to 3.0 myself instead of letting Ed do it 8!^). I've now managed to pull things together so that they're generally usable and brought them up to date with r1588 from the epydoc svn repository.

The files that we've added or changed are:

 [source:branches/epydoc-3/utils/epydoc/src/tools/epydoc.sty@2141 epydoc.sty]:: 

  A LaTeX style file that produces a reasonable facsimile of what comes out of stock epydoc. The remaining discrepancies are either due to bugs in !r1588 or had a poor cost/benefit until I knew whether this was even of interest to the epydoc developers. I'm happy to try to fix any remaining issues.

 [source:branches/epydoc-3/utils/epydoc/src/epydoc/docwriter/latex.py@2141 latex.py] ([diff:vendor/epydoc/3.0-r1588/src/epydoc/docwriter/latex.py@2141//branches/epydoc-3/utils/epydoc/src/epydoc/docwriter/latex.py@2141 diff vs. r1588])::

  Abstracted the markup, leaving the formatting details to a LaTeX .sty file.

 [source:branches/epydoc-3/utils/epydoc/src/epydoc/markup/restructuredtext.py@2141 restructuredtext.py] ([diff:vendor/epydoc/3.0-r1588/src/epydoc/markup/restructuredtext.py@2141//branches/epydoc-3/utils/epydoc/src/epydoc/markup/restructuredtext.py@2141 diff vs. r1588]):: 

  Markup for [http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions reST admonitions].

 [source:branches/epydoc-3/utils/epydoc/src/epydoc/cli.py@2141 cli.py] ([diff:vendor/epydoc/3.0-r1588/src/epydoc/cli.py@2141//branches/epydoc-3/utils/epydoc/src/epydoc/cli.py@2141 diff vs. r1588]):: 

  * Added `--[no-]sub-modules` options to control output of `write_module_list()` (we prefer to use a minitoc for this information).

  * Added `--pdflatex` option (latex -> dvips -> ps2pdf is so 20^th^ century)

I wanted to move most of the formatting out of [source:branches/epydoc-3/utils/epydoc/src/epydoc/markup/epytext.py@2137#L1896] as well, but my efforts there caused more problems than they solved.

A few examples to compare the output:

 attachment:api-r1588.pdf:

  epdoc APIs processed with epydoc [http://epydoc.svn.sourceforge.net/viewvc/epydoc/trunk/epydoc/?pathrev=1588 r1588]

 attachment:api-epydoc_sty.pdf:

  epdoc APIs processed with hacked epydoc and formatted with [source:branches/epydoc-3/utils/epydoc/src/tools/epydoc.sty@2141 epydoc.sty]

 attachment:api-fipy_sty.pdf:

  epdoc APIs processed with hacked epydoc and formatted with [source:branches/epydoc-3/documentation/manual/fipy.sty@2141 fipy.sty] (this isn't a petition for a change to what epydoc-LaTeX output should look like; just an example of what's possible when content is separated from markup).