There must be something I don't understand about how to use HappyDoc, because directory related behavior is bizarre and index.html files for parent packages contain no useful information.
Given a Unix command line as follows:
happydoc -T SingleFile --no-private-names --no-comments -title "Foo Framework" /home/rwentwor/jytest/jythonlib
where the source files are in /home/rwentwor/jytest/jythonlib/jyfulfill/support/util and there are __init__.py files in /home/rwentwor/jytest/jythonlib/jyfulfill/ and subdirectories thereof...
I get a doc directory containing:
Note that: the directory structure is recursively nested three times. There are index.html files in only a few places. Except for the last index.html file (which contains documentation from my source files) the other index.html files are useless: they contain no listing of sub-packages or hyperlinks to anything but themselves.
No, this is a bug. You are using it properly.
Try these commands instead:
% cd /home/rwentwor/jytest
% happydoc -T SingleFile --no-private-names --no-comments -title "Foo Framework" jythonlib
That should give you a doc directory with everything under jythonlib documented inside.
Thanks, that fixes the bizarre recursive directory structure.
But it doesn't solve my problem with index.html. The display of doc/jythonlib/jyfulfill/index.html looks something like the following:
Table of contents
No package level documentation
Docstring from __init__ module
Table of Contents
There are a number of problems with this:
1) Most seriously, jyfulfill contains several subpackages, but these are not mentioned, nor is there any link to their documentation.
2) The two "Table of Contents" links link back to this same page -- they go nowhere and seem to serve little function.
3) What should presumably be "Title: jyfulfill" instead is truncated to "itle: jyfulfill".
Is there some way to coerce better behavior with respect to these issues?
So the index.html file doesn't actually contain HTML? I wonder if the SingleFile docset is broken. I don't use that one very often. Does it work if you don't specify that option?
Yes, index.html contains HTML. That's not the problem. My main question is: how do I make it so that index.html for a package includes links to the documentation for sub-packages?
Ok, I misunderstood what you were saying.
The index.html file should just include those references. Try the default docset. If that works (generating multiple index.html files that are cross-linked) then the problem is in the SingleFile docset. If it does not work, then something else is going on.
Ok, yes, with the default docset those subpackages do show up.
I also managed to clear up the problem with titles being "itle: packagename". The problem was I was using "-title" as an option instead of "-t".
Remaining minor oddities:
1) The package level documentation contains the complete documentation from __init__.py, and also include a link (in the modules and packages section) to another page that also includes all the documentation from __init__.py.
2) All pages include "Table of Contents" links. For module documentation pages, these links take one back to the root page of the documentation tree. But for package documentation pages, these links link back to the current page, taking you nowhere."
While it might be nice to have ways of dealing with these quirks, the system is usable at this point. Is there any way of addressing (1) and/or (2)?
Ok, good, so at least you're able to generate something useful even if it isn't in the format you want.
The remaining oddities:
1. This is by design. At least, the __init__.py module is not specifically excluded from the list of modules. I think I've had this behavior mentioned as odd before, but no one took the time to write up a feature request and it doesn't bother me, so I haven't done anything about it.
2. This is a bug, and it would be helpful if you would submit it to the bug tracker so I don't forget to look into the problem.