JCite – Java Source Code Citation System

JCite cites snippets of Java source code or Excel sheets into HTML documents – API documentation, for instance. Citing from tests, or tested code, lets you guarantee that your examples really work. And they get automatic syntax highlighting.

To get a feel for the results you can achieve, take a look at:

• Citing Java Source Code
• Citing Excel Spreadsheets
• Citing Plain Text Files
• Citing File Paths
• Including HTML Files

And here’s how to use and customize it:

• Using Citations As Tripwires
• Running JCite
• Using JCite with JavaDoc
• CSS Styles Used
• Extending JCite

I have also written some articles which put JCite into a broader perspective:

• On Literate Testing (article)
• Beyond TDD: Documentation Driven Development (blog post)
• Source Citing: Making Examples Work (article)

“Example isn’t another way to teach, it is the only way to teach.” (Albert Einstein)

License

JCite is open source under a BSD-style license. The required Java2Html library is Open Source under the GPL or CPL1.0 license (whichever of both fits your needs).

Download

jcite-1.13.0-bin.zip : Binary release, including the required open-source Java2Html library. Needs at least Java 1.5 to run.

jcite-1.13.0-excel-bin.zip : Binary release for the Excel citation plugin, including the required open-source JExcelAPI library.

jcite-1.13.0-src.zip : Source code for JCite, including tests and examples. External libraries and build tools are not included in the download. For the required libraries, download the respective binary release of JCite first. In order to run the Ant build script, you need Ant. If you want to run the tests, you need JUnit and Rextile. To build a distribution, you need CheckStyle.

Release History

Contributing

JCite is available from the Google Code Hosting archive as a Mercurial repository. There is also a discussion group.

Alternatives

If you think you’d be more comfortable with a tool that lets you write unchecked example source directly in the JavaDoc comments, you might want to take a look at the SAM Example Taglet.

Another similar tool is Bumblebee. It lets you write your documentation in inlined comments.