JQuery documentation in PDF

This is documentation for old versions; because of changes in the way the JQuery source and documentation is organized, my scripts no longer work with the current version.

I’ve been fascinated for a while by JQuery, a rather fine javascript library, a fact that I’ve alluded to in the past, but which I appear to have started paying attention to sometime in late August. I use it at work, and I’ve actually tried to unbold every message in its mailing list, once.

One of the nicer things about JQuery is its documentation. However, I came across Chris Heilmann’s complaint that JQuery (and other javascript libraries) should have its documentation readily available for offline reading in PDF. Inspired by this, I decided to write a utility to build a PDF file from the JQuery documentation.

Well, now here it is, a birthday present for JQuery.

UPDATED for version 1.1.4:

• jquery docs [121k pdf]
• jquery with official plugins [206k pdf]

Older versions, JQuery 1.1:

• jquery-docs-with-all-plugins[ 275k pdf]
• jquery-docs-with-plugins [186k pdf]
• jquery-docs [116k pdf]

The PDFs created have clickable tables of contents for navigation, and aren’t intended for printing.

How I did this

The JQuery subversion repository already includes scripts that extract and create XML files from the comments in its source files, so I decided to leverage that. I thought of using Perl, parsing the XML documentation and other scary thoughts, then noticed that JQuery uses ant, and that its build scripts are actually written in Javascript, and use Rhino (Mozilla’s implementation of Javascript written in Java) to run. I found a free java library for generating PDF files called iText. After some reading on the web and experimentation, I figured out how to run a Javascript script from the command line while accessing external java modules. iText itself has lots of code samples in its online tutorial, and converting them to Javascript is pretty simple.

My script, a mash-up of an iText example and the existing docs.js script that generates the XML docs, is here:

• pdfDocs.js

How to use it

• Create a local copy of the JQuery subversion repository, by checking out svn://jquery.com/trunk to a local directory.
• Make sure you have java and ant installed to work from the command line (I haven’t gotten around to adding this to the makefile yet).
• Download the iText jar file and put it in the jquery/build subdirectory.
• Save my script to the jquery/build/docs subdirectory.
• Merge the existing jquery/build.xml file with my modified one, or edit the build.xml file to add the target definitions below.
• Save the JQuery hat logo (hat.gif) in the jquery directory (this is needed for the cover page – thanks to Sam Collett for suggesting I add one).
• The PDF docs aren’t created by default. To create them, type ant pdf_docs (to create a file with just the JQuery documentation) or ant pdf_docs_with_plugins (to include documentation from all the plugins listed in the build file). These targets are based on the matching docs targets.

The change to the build.xml file:

<!-- PDF DOCS STUFF --> <property description="IText PDF generating library" name="ITEXT" value="${BUILD_DIR}/itext-1.4.8.jar" />

<target name="pdf_docs_with_plugins" depends="jquery_with_plugins"

description="Reads inline docs from source and from plugins and creates a PDF file">

<echo message="Building PDF Documentation" />

<java fork="true" classname="org.mozilla.javascript.tools.shell.Main">

<classpath>

<pathelement location="${JAR}" />

<pathelement location="${ITEXT}" />

</classpath>

<arg value="${BUILD_DIR}/docs/pdfDocs.js" />

<arg value="${JQ}" />

<arg value="${DOCS_DIR}/jquery-docs-with-plugins.pdf" />

</java>

<echo message="PDF Documentation built." />

</target>

<target name="pdf_docs" depends="jquery"

description="Reads inline docs from source and creates a PDF file">

<echo message="Building PDF Documentation" />

<java fork="true" classname="org.mozilla.javascript.tools.shell.Main">

<classpath>

<pathelement location="${JAR}" />

<pathelement location="${ITEXT}" />

</classpath>

<arg value="${BUILD_DIR}/docs/pdfDocs.js" />

<arg value="${JQ}" />

<arg value="${DOCS_DIR}/jquery-docs.pdf" />

</java>

<echo message="PDF Documentation built." />

</target>

<!-- END PDF DOCS STUFF -->

If you want to try out the script from the command line, it requires this convulated syntax:

java-cp build/itext-1.4.8.jar:build/js.jar

org.mozilla.javascript.tools.shell.Main

build/docs/pdfDocs.js

dist/jquery.js

... any additional javascript source files you want to extract docs from ... 

output_file_name.pdf

Everything after the script name is an argument to my script; everything before is an argument to java. These stick two jar files in the classpath (-cp) and then explicitly tell java to execute the Javascript interpreter (org.mozilla.javascript.tools.shell.Main), which gets the rest of the arguments.