Generating ready to print PDF Javadoc file¶

Some time ago, when writing project from Computer Networks in Java me and my friend want to generate Javadoc in PDF. On Sun tech support is information how to generate Javadoc PDF but it was not really usefull.

Reading this article you have to pass few steps and install additional software which is not nice.

After some time I have decided to search other way to do it. I found two applications doclets worth using.

What is doclet?: Doclet is programs (it’s some kind of plugin to Javadoc tool) written in the Java programming language that use the doclet API to specify the content and format of the output of the Javadoc tool. By default, the Javadoc tool uses the „standard” doclet provided by Sun Microsystems to generate API documentation in HTML format. However, user can write own doclets and start generating documentation in custom format for example PDF, PS, TXT.

PDFDoclet¶

PDFDoclet is doclet build using iText library (for generating PDF). For proper working it requires only PDFDoclet jar file. On Source Forge site author of PDFDoclet says:

PDFDoclet is a straightforward, simple-to-use 100% pure Java solution. It creates a PDF file as similar as possible to a typical HTML javadoc. As far I remember the generated javadoc can be customized by specifying a header/footer text and a cover page in XHTML. Running PDFDoclet for first time is not as straightforward as it should be, but in the download bundle some example scripts can be found.

PDFDoclet - how to generate PDF javadoc?¶

It’s not so straight forward that it could be ;) mostly because user is obliged to specify list of packages which has to be in PDF file.

I really don’t like this part and I wrote bash script which simplifies this.

Script gen-pdf-javadoc-pdfdoclet.sh¶

Here is source code (it can also be downloaded from Google Code gen-pdf-javadoc-pdfdoclet.sh):

#!/bin/bash

# Author: Tomasz Gawęda - blog.0x1fff.com
# Date:  2009.07.13
# License: BSD
# Description: Simple shell script to generate pdf
#  javadoc (without ANT) from small
#  Java projects - use under Linux.
#
# Dependicies: Bash
#  Java JDK - 1.6
#  PDFDoclet
#

# Set the JAVA_HOME variable correctly!!!
JAVA_HOME="/usr/lib/jvm/java-6-sun-1.6.0.13"
PATH="$PATH:$JAVA_HOME/bin"
PATH_DOCLET_JAR=pdfdoclet-1.0.2-all.jar
CUSTOM_CONF='conf.properties'

DEFAULT_CONFIG=<<END_DEFAULT_CONFIG
#
# Default config to pdf doclet
#

# Prints @author tags if set to "yes".
tag.author=yes

# Prints @version tags if set to "yes".
tag.version=yes

# Prints @since tags if set to "yes".
tag.since=no

# Show the Summary Tables if set to "yes".
summary.table=yes

# Encrypts the document if set to "yes".
encrypted=yes

# The following property is ignored
# if "encrypted" is not set to yes.
allow.printing=yes

# Creates hyperlinks if set to "yes".
# For print documents, use "no", so
# there will be no underscores.
create.links=yes

# Creates an alphabetical index of all
# classes and members at the end of the
# document if set to "yes".
create.index=yes

# Creates a navigation frame (or PDF
# outline tree) if set to "yes".
create.frame=yes

# Creates a title page at the beginning
# of the document if set to "yes".
api.title.page=yes

# Defines the path of the HTML file that
# should be used as the title page.
#api.title.file=example/laby/laby_title.html

# Defines the title on the title page if
# no external HTML page is used.
api.title=Hello Doclet!

# Defines the copyright text on the
# title page.
api.copyright=Tom

# Defines the author text on the
# title page.
api.author=Tomasz Gawęda

# Defines packages whose classes should not
# be printed fully qualified. For example, every
# Java developer probably knows that "String" is in
# the "java.lang" package, so instead of wasting
# page spage, just get rid of that package qualifier:
# dontspec=java.lang
dontspec=java.lang,java.io,java.util

#font.text.name=example/fonts/Windows/Vera.ttf
#font.text.name=example/fonts/Windows/Arial.TTF
#font.text.name=example/fonts/garait.ttf
#font.code.name=example/fonts/SF Arch Rival v1.0/SF Arch Rival.ttf
#font.text.enc=Cp1252
#font.text.enc=ISO-8859-9
#font.code.enc=UTF-8

END_DEFAULT_CONFIG

## DO NOT EDIT BELOW THIS LINE ##

########################################################
########################################################
########################################################
########################################################
########################################################
########################################################

# check command line params
if [ $# -lt 2 ] ; then
 echo usage: $0 src-dir new-pdf-file
 exit 1
fi

if [ ! -r $PATH_DOCLET_JAR ] ; then
 echo "FATAL: Unable to find doclet in $PATH_DOCLET_JAR"
 exit 1
fi

DOCLET_MAIN=com.tarsec.javadoc.pdfdoclet.PDFDoclet
JAVADOC=`which javadoc`
if [ $? -ne 0 ] ; then
 echo "FATAL: Unable to find javadoc in $PATH"
 exit 1
fi
echo "JavaDoc found in $JAVADOC"

SRCDIR=$1
if [ ! -d $SRCDIR ] ; then
 echo "FATAL: Directory $SRCDIR does not exists"
 exit 1
fi
echo "Src directory of program exists ($SRCDIR)"

OUTPUT=$2
if [ -e $OUTPUT ] ; then
 echo "WARNING: Out document exists - will be overwritten ($OUTPUT)"
 echo "WARNING: Got five seconds to break"
 sleep 3
 echo "WARNING: Got two seconds to break"
 sleep 2
 echo "WARNING: Too late ..."
fi

DEL_CONF=0
echo "Checking if exists custom configuration ($CUSTOM_CONF)"
if [ ! -r $CUSTOM_CONF ] ; then
 echo "Custom configuration doesn't exists using default"
 echo $DEFAULT_CONFIG > $CUSTOM_CONF
 DEL_CONF=1
fi

echo "Starting analyzing sources - finding packages"
# find all packages
PACKAGES=`find $SRCDIR -type d -and -not -empty|sed s#$SRCDIR##g | sed s#/#.#g`
echo "Found "`echo $PACKAGES | wc -l `" packages"

export JAVA_HOME PATH DOCLET_MAIN PATH_DOCLET_JAR JAVADOC

echo "Running JavaDoc"
# Run
$JAVADOC -doclet $DOCLET_MAIN -docletpath $PATH_DOCLET_JAR -pdf $OUTPUT -config $CUSTOM_CONF -sourcepath $SRCDIR $PACKAGES

echo "JavaDoc finished with exit status "$?

if [ $DEL_CONF ] ; then
 echo "Cleanning up"
 rm $CUSTOM_CONF
fi

Usage of gen-pdf-javadoc-pdfdoclet.sh¶

bash gen-pdf-javadoc-pdfdoclet.sh /home/johny/NetBeansProjects/HelloWorldApp/src/ HelloWorld_pdfdoclet.pdf

Auriga Doclet¶

Auriga Doclet is a Doclet which can generate Java API Documentation in many formats:

Formatting Object(FO)

PDF

Postscript

PCL

SVG

The generated javadoc can be customized by specifying a header/footer text and a cover page in XHTML.

Auriga Doclet - how to generate PDF javadoc?¶

Again it could be much easier, but it can be done - I’ve also wrote simple bash script to make it easier.

Script gen-pdf-javadoc-auriga.sh¶

Here is source code (it can also be downloaded from Google Code gen-pdf-javadoc-auriga.sh):

#!/bin/bash

# Author: Tomasz Gawęda - blog.0x1fff.com
# Date:  2009.07.13
# License: BSD
# Description: Simple shell script to generate pdf
#  javadoc (without ANT) from small
#  Java projects - use under Linux.
#
# Dependicies: Bash
#  Java JDK - 1.6
#  AurigaDoclet jar file (http://sourceforge.net/projects/aurigadoclet/)
#
# Notes: Has to be run from directory where was extracted
#  (additional libs are needed) catalog - lib/

# Set the JAVA_HOME variable correctly!!!
JAVA_HOME="/usr/lib/jvm/java-6-sun-1.6.0.13"
PATH="$PATH:$JAVA_HOME/bin"
PATH_DOCLET_JAR=bin/AurigaDoclet.jar

## DO NOT EDIT BELOW THIS LINE ##

########################################################
########################################################
########################################################
########################################################
########################################################
########################################################

# check command line args
if [ $# -lt 2 ] ; then
 echo usage: $0 src-dir new-pdf-file
 exit 1
fi

if [ ! -r $PATH_DOCLET_JAR ] ; then
 echo "FATAL: Unable to find doclet in $PATH_DOCLET_JAR"
 exit 1
fi

DOCLET_MAIN=com.aurigalogic.doclet.core.Doclet
JAVADOC=`which javadoc`
if [ $? -ne 0 ] ; then
 echo "FATAL: Unable to find javadoc in $PATH"
 exit 1
fi
echo "JavaDoc found in $JAVADOC"

SRCDIR=$1
if [ ! -d $SRCDIR ] ; then
 echo "FATAL: Directory $SRCDIR does not exists"
 exit 1
fi
echo "Src directory of program exists ($SRCDIR)"

OUTPUT=$2
if [ -e $OUTPUT ] ; then
 echo "WARNING: Out document exists - will be overwritten ($OUTPUT)"
 echo "WARNING: Got five seconds to break"
 sleep 3
 echo "WARNING: Got two seconds to break"
 sleep 2
 echo "WARNING: Too late ..."
fi

echo "Starting analyzing sources - finding packages"
# find all packages
PACKAGES=`find $SRCDIR -type d -and -not -empty|sed s#$SRCDIR##g | sed s#/#.#g`
echo "Found "`echo $PACKAGES | wc -l `" packages"

export JAVA_HOME PATH DOCLET_MAIN PATH_DOCLET_JAR JAVADOC

echo "Running JavaDoc"

$JAVADOC -doclet $DOCLET_MAIN -docletpath $PATH_DOCLET_JAR -format pdf -out $OUTPUT -sourcepath $SRCDIR $PACKAGES

echo "JavaDoc finished with exit status "$?

Usage of gen-pdf-javadoc-auriga.sh¶

bash gen-pdf-javadoc-auriga.sh /home/johny/NetBeansProjects/HelloWorldApp/src/ HelloWorld_auriga.pdf

Warning about using Auriga Doclet - pdf generator script¶

This script have to be run from Auriga Doclet directory!!! (it requires additional third party libs which are not included in jar but are present in lib folder).

Summary¶

Both projects (PDFDoclet and Auriga Doclet) are doing thweir job with Java 1.6 on Linux. I think more straight forward and with more possibilities to expand is PDF Doclet, but Auriga is also very customizable - both are worth using, but i prefer PDFDoclet :) - mostly because I have only one additional jar file.

I hope that this article was easy to understand - comments welcome.

Generating ready to print PDF Javadoc file¶

PDFDoclet¶

PDFDoclet - how to generate PDF javadoc?¶

Script gen-pdf-javadoc-pdfdoclet.sh¶

Usage of gen-pdf-javadoc-pdfdoclet.sh¶

Auriga Doclet¶

Auriga Doclet - how to generate PDF javadoc?¶

Script gen-pdf-javadoc-auriga.sh¶

Usage of gen-pdf-javadoc-auriga.sh¶

Warning about using Auriga Doclet - pdf generator script¶

Summary¶

Comments

blog.0x1fff.com

this.post

blog.tags

blog.archives

blog.pages