Re: [Epydoc-devel] Documentation not associated with a particular module, function, class, or method

[Joseph T. <tu...@gm...>]

I guess I was thinking something along the lines of the Doxygen \page
command:
   http://www.stack.nl/~dimitri/doxygen/commands.html#cmdpage
" Indicates that a comment block contains a piece of documentation that is
not directly related to one specific class, file or member. The HTML
generator creates a page containing the documentation. The [image:
$\mbox{\LaTeX}$] generator starts a new section in the chapter `Page
documentation'."


If you just want to convert stand-alone epytext to html, it's not too
> hard.  But if you want it to include links into the documentation
> generated by epydoc, then things get a bit trickier.


Yeah, I wanted the tricky thing :^)

The code following this email should do basically what you want -- it
> runs the epydoc command line interface (with options taken from
> sys.argv), and then has some code at the end to parse a text file
> containing epytext material (linking it to the docs), and write it as
> html to the output directory.  It's a bit hackish, though, I'm afraid.


I wasn't able to figure out how to invoke this code.
Does it provide links to and from graph? That's what I need.

A better solution would probably be to add the ability for epydoc to
> read files containing epytext (or rst) and convert them natively..
> something like:
>
>  % epydoc my_package/ --rst-file my_docfile.rst --epytext-file
> my_other_docfile.txt


That sounds great.
Ideally, I could do: --epytext-file extra/*.txt

Some issues might have to be worked out though, such as what files
> they would be written to in the output, whether they could get
> referenced by docstrings in python code, etc.


Instead of -module  -pysrc or -class, just use -page (as does doxygen).
They should definitely be able to reference and be referenced by docstrings
in the python code.
The idea for "page" is to be able to describe general concepts and design
decisions, and link to them in docstrings as needed.

Thanks,
   Joseph

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