[Doc-SIG] list of tools for the doc-sig page

[David Goodger]

Edward Loper wrote:
> I think that the python doc-sig page <http://www.python.org/sigs/
> doc-sig/> should include a list of the tools that are currently
> available for automatically extracting API documentation (pydoc,
> HappyDoc, docutils, etc).

I agree.  Coincidentally, I've been working on updating the Doc-SIG pages.
Fred Drake okayed an initial draft, although I've revised it since and
(unless Fred says not to bother; Fred?) I'll run it by him again.  I've
added Docutils and epydoc, and removed some outdated material.  The "PSA as
a Catalyst" section (status page) is obsolete; Fred suggested it be ripped
out, and I agree.  The "Continuing questions" section should also be either
ripped out or reworked; I think most of the questions are no longer
current/continuing.  Given that, and the amount of duplication, I think the
home page (http://www.python.org/sigs/doc-sig/index.html) and status page
(http://www.python.org/sigs/doc-sig/status.html) ought to be merged.

> I wrote up a table summarizing the tools that I know of,

Looks good.  I think it would be a fine addition to the Doc-SIG page.

> (who maintains that page?).

Nobody has been maintaining it of late.  I get the impression from Fred that
he'd be happy if anyone took over.  I have Python CVS access now, so I could
coordinate at least.

> I'll also include a slightly reduced/summarized text version of the
> table below, in case that's more convenient for some people.

Does epytext handle *that*?  ;-)

> Also, if any of the information I listed is incorrect/incomplete, or if
> I left out any tools that you know of, please let me know.

Some corrections to the Docutils entry: HTML, XML output formats, with
LaTeX, DocBook, and PDF on the way (with a caveat); most of the code is
public domain, with some Python license, some other OSI-approved (details in
http://docutils.sf.net/COPYING.html).  The caveat is that the docstring
extraction part is very much under construction (although it seems that
Richard Jones has been scratching an itch; gotta take a look at what he's up
to).

> I think we should try to make this list as complete as possible.

Sounds good.

-- 
David Goodger  <goodger@users.sourceforge.net>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/