25

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?

frogatto
  • 28,539
  • 11
  • 83
  • 129
chesterbr
  • 2,940
  • 3
  • 29
  • 26

4 Answers4

23

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 the software on the releases page;

  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; For Windows users, dir /s/b *.html > files.txt should do the same (but keep in mind you may have to replace \s with /s if they appear like so on the next step).

  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...

EDIT: software is now free from original author; updated links, thank you @mohammed

chesterbr
  • 2,940
  • 3
  • 29
  • 26
  • 3
    for those on Mac OS, a package can be donwloaded from http://code.google.com/p/rudix/wiki/htmldoc. It has no GUI so you will have to find an [example of .book file](http://sunsite.ualberta.ca/Documentation/Misc/htmldoc-1.8.23/htmldoc.book) and modify it. Then use the command `htmldoc --batch htmldoc.book` to generate the pdf – emerix Jan 31 '13 at 16:15
  • 2
    FYI was able to find the mac version binary here: http://rudix.org/packages/htmldoc.html notice that it does have a GUI on Yosemite – Shai Almog Feb 25 '16 at 05:20
  • 1
    the suggested procedure works quite well under windows, but I had to replace all "\" characters by "/" in the generated list that I insert inside the .book file – jmd May 04 '17 at 16:02
  • Thanks @jmd, added that info to the procedure. – chesterbr May 05 '17 at 16:41
  • 1
    The link in answer seems to be broken/moved. here is the updated on https://www.msweet.org/htmldoc/index.html – Mohammed Aug 27 '19 at 11:13
2

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.

MCory
  • 437
  • 2
  • 13
  • 1
    From that page I've tried the MIF Doclet (not compatible with annotations), html2ps (near impossible to make work on Windows, which is what I'm stuck with overseas right now) and HTMLDOC (which requires either purchasing or a build that did not succeed on my first try). Still have to check PDFDoclet, but decided to ask here first just to be sure (after all, two doclets not doing precisely the same thing may spot something obvious I may be missing, parameter/setup-wise). Have you (or anyone) used it before in such conditions? Thanks! – chesterbr Feb 23 '10 at 22:38
  • Unfortunately, no, I haven't -- I'm working with a small enough team at the moment that there isn't much benefit to printing the docs out, and the code is still new enough to where a hard copy of the docs would be outdated in a couple of weeks anyways. – MCory Feb 23 '10 at 22:41
  • Yes, I totally agree: the real value of most JavaDocs are their "live" characteristic. But this was an external request... :-/ – chesterbr Feb 24 '10 at 04:47
  • Something else you may want to consider is the iText java library and roling your own PDF generator. I'm adding this from my phone, so its difficult for me to get the link at the moment, but its a fairly popular library -- just google iText java pdf. It'll be a bit more difficult than just running a tool, but you can always release it to the public for anyone else who has this problem. Unfortunately, you'll probably need another library to parse th HTML files - maybe not, but most likely, since I think iText is just PDF. – MCory Feb 24 '10 at 05:46
  • And no luck with PDFDoclet also - it generates nice-looking PDFs, but ignores the overview.html (at least it prints package descriptions, which AurigaDoclet ignores). Tried using the -overview parameter (for which PDFDoclet reports an error, regardless of what I set as the overview file, suggesting it's refusing the parameter right away, and AurigaDoclet is just swalloing) and also adding the default package as "." (which javadoc refuses). Stuck :-( – chesterbr Feb 24 '10 at 06:13
  • MCory, thank you for the suggestion. I ended up using HTMLDOC (see my own answer). – chesterbr Feb 24 '10 at 07:35
2

AurigaDoclet fails to process package.html. For a fix see my comment at https://sourceforge.net/projects/aurigadoclet/forums/forum/339169/topic/1572199/index/page/1

weberjn
  • 1,840
  • 20
  • 24
2

If this question was bumped anyways, I can use this to link my ltxdoclet project.

This creates from the source (by being a JavaDoc plugin) documentation in LaTeX format, which you then can pass through PdfLaTeX to produce a PDF.

Optionally it also can include pretty-printed source code.

Paŭlo Ebermann
  • 73,284
  • 20
  • 146
  • 210