«

I've been trying to use "happydoc" to document a source
tree that I'm working on. It does pretty much what I want,
except:

Version 2.1:
Creates a weird directory structure for the HTML pages
it generates -- they embed the full path to the working
copy of the sources, which, beyond just being ugly,
would be pretty annoying for a collaborative project
(each collaborator's copy would produce documentation
in separate directories, probably resulting in duplication).

Version 3-alpha:
Solves that problem, but very incomplete compared to
2.1, and apparently abandoned in 2003 (maybe because
of pydoc?). Various options aren't available, and, for
example it forces me to use "README.txt" instead of
just "README" if I want it to collect that information.

Neither version documents class attributes, which is somewhat
annoying, because they are part of my interface. But I can fix
this with the docstrings, of course.

Now I've considered using pydoc, but it seems to be very weak
in this kind of application (generating a tree of static HTML pages
to provide library documentation). On the plus side, I find its
overall layout prettier, and it does include attributes.

But it also includes a lot of garbage (such as symbols loaded
by "from pygame.locals import *"), doesn't apparently understand
the structured text docstrings, and finally, it chokes on some
modules because it can't find all of their imports (because I'm
trying to run it from the documentation directory). I don't
think happydoc has this problem, because it doesn't
attempt to import the module in order to generate documentation,
so it only documents what is actually defined in that module. It
also reads comment lines, which can be a plus.

Unlike happydoc, pydoc doesn't seem to have many command
line options for changing any of this behavior, so if you don't like
it, you seem to be stuck.

So while I use pydoc quite a lot for on-the-fly documentation,
I'm not so happy with it as a docset generator (or maybe I just
don't know how to get it to do what I want?).

What I really want to do is to have a set of (static) HTML documentation
pages that I write, that are deep-linked into an automatically
generated set of library documentation.

Any suggestions on getting pydoc, happydoc, or yet another
documentation generator to do this, would be greatly appreciated.

Cheers,
Terry


--
Terry Hancock ( hancock at anansispaceworks.com )
Anansi Spaceworks http://www.anansispaceworks.com