How to generate a PDF from JavaDoc (including overview and package summaries)

Question

I have written extensive JavaDoc documentation on my application, and added lots of useful info at overview.html and package.html files (including links on the former to illustrations in doc-files/). Maven's Javadoc plugin nicely uses the standard javadoc tool to generate the classic JavaDoc frameset, but now I need to generate a PDF with the whole documentation.

AurigaDoclet generates very pretty PDFs, and I was able to make DocFlex work also. However, both ignore my overview.html and package.html files (tried both inside and outside Maven - the PDF will be a once-only thing, since I'd rather have the HTMLs on the long run).

Does anyone know how to make AurigaDoclet recoginze my non-Java files? Or, alternatively, another to generate a decent-looking PDF from either the source code or the JavaDoc-generated HTML?

Thank you!

Answer 1

According to the Sun JavaDoc FAQ, there's a couple of options -- mostly free, with one or two commercial offerings as well. Check it out at http://java.sun.com/j2se/javadoc/faq/index.html#print.

Answer 2

Nailed it. After trying all the possible tools to generate straight from the source, I returned to HTMLDOC. It is not JavaDoc-aware, but it is so well built that a few tweaks are enough to make it generate a pretty usable PDF.

Here goes a step-by-step description of how I did it:

1. Download a free build of the software (the official site version requires a license, but it's GPL-ed, so you can find free binaries such as this one, which is a simple and functional installer for Windows);

2. Generate your traditional HTML docs in your preferred way (Ant, Maven, command-line javadoc - your choice);

3. The GUI is nice, but adding all files manually can be cumbersome, so just create a .book file with Document Type set to "Web Page", add one of the HTML files from your generated javadoc's root folder (e.g., overview-summary.html, anyone will do, it's just for reference on step 5). On the Output tab select the PDF format and set a name for it, and add other options to your heart's content (logos, colors, lots of cool stuff here). Save this project (say, myjavadocpdf.book) and close the GUI

4. Generate a list of all HTML files in your javadoc. I did it with Cygwin's find command (my DOS/cmd shell days are long over), but you can do anything you want, as long as you get a file list. In my case a find . | grep html$ | sort -r > files.txt did the trick;

5. Open the .book file generated on step 3 in your favorite pure text editor (as a programmer you should have strong opinions on that, so will keep my opinions to myself - NOT ;-) ) and append the list generated on step 4 to this .book file (it keeps the list of files at the end, making life really easy). Don't forget to fix the relative paths, if needed with a global search/replace (that's why you needed at least one file added on step 3 - to see which file path pattern htmldoc expects);

6. Now you should sort the files in a convenient order. I put my overview first, then package descriptions and each class, then the full index, and everything else at the end. Remember that any file you delete will become an external (hence broken) link, so choose wisely;

7. Save your .book file and re-open it on HTMLDOC. Voila: all files added and sorted. Click on generate. That's it!

You may want to fiddle with images (hint: use HTML width/height, not style/css). In the end, the resulting file is surprisingly good: nice looking and fully navigable for internal and external links. Impressive when you consider that the tool is not Java(Doc) aware at all...

Answer 3

@chester wrote:

AurigaDoclet generates very pretty PDFs, and I was able to make DocFlex work also. However, both ignore my overview.html and package.html files (tried both inside and outside Maven - the PDF will be a once-only thing, since I'd rather have the HTMLs on the long run).

In fact, neither overview.html nor package.html files are ever processed specifically by any Javadoc doclet! Rather those files are picked up automatically by the Javadoc core itself. Javadoc reads, parses and pre-processes the content of those files. Only after that that content is fed to a doclet. The doclet does not even know where all those descriptions come from.

So, you should not blame AurigaDoclet or DocFlex/Javadoc for your failure. They are just Javadoc doclets, that is Javadoc plug-ins.

Instead, you should know how to specify the overview.html and package.html files to Javadoc in general. That will work the same with any doclets you use (so long as Javadoc itself is involved).

The overview.html should be specified using -overview Javadoc command-line option. Read about this here: "http://java.sun.com/javase/6/docs/technotes/tools/windows/javadoc.html#overview"

The package.html should be placed simply in the corresponding package directory of your Java sources. It will be picked up there by Javadoc automatically. No specific command-line options/settings are needed for this!

Regards,

Leonid Rudy

www.docflex.com