Daniele,

Have you considered the use of reStructuredText syntax to produce your
documentation?

I did consider it, but I am not sure if it solves our usage requirements.
Maybe you can help?
 
Just like epytext it can be used to produce API documentation
with Epydoc, but it is already geared towards the production of standalone
documents too (with titles, ToC, metadata etc.) and is ready to produce html,
pdf and some other fancy format.

Okay. But how do I create a standalone document about the "graph" concept and then, within the code main code, link to the "graph" concept using @see or L{graph}? This is what I couldn't figure out.


Epydoc also contains a script - apirst2html.py - allowing a standalone reST
document to reference API docs generated with Epydoc itself, e.g. citing
:api:`some_function()` or :api:`module.Class`. The script converts the
document into HTML and links the objects marked with the above syntax to the
matching epydoc-generated API docs.

What about linking from epydoc comments to the standalone reST? Is there a clean approach (not just hardcoding an external URL)?

Thanks,
  Joseph

--
Academic: http://www-etud.iro.umontreal.ca/~turian/
Business: http://www.metaoptimize.com/