Lemma - creating valid software documentation

Lemma is an easy to use and powerful software documentation tool for Java developers. It enables automatic testing of all code snippets in your software's manual, using an innovative citation mechanism.

Instead of copying and pasting code examples from your source into your text processor, you simply place a citation marker within your documentation text. Lemma will now find your tested source code, extract the lines you need, and insert them in the right place when you build your documentation.

The source code Lemma is citing from is typically unit test source code. Therefore, all code examples in your documentation can be tested automatically. Stop writing anemic and artificial unit tests for your software - write real examples that are helpful to your users and include them automatically within your documentation.

Getting started

If you already use Maven to build your project and run unit tests, Lemma can be integrated in one minute.

Assuming that your project's artifact identifier is myproject, create the file src/manual/myproject-manual.xhtml with the following content:

<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title>My Manual</title>
</head>

<body>

<div>
   <a class="citation" href="javadoc://com.myproject.MyUnitTest"/>
</div>

</body>
</html>

Now edit your com.project.MyUnitTest class - which should be located in your test source directory - and create a regular Javadoc comment on the class. Any Javadoc comment that is well-formed XHTML will work, and citation processing is recursive (you can add citation anchors everywhere):

package com.myproject;

/**
 * Some documentation
 * <p>
 * My text paragraph.
 * </p>
 * <a class="citation" href="javacode://this#someMethod()"/>
 */
public class MyUnitTest {

    public void someMethod() {
        ...
    }
}

Add the Lemma plugin repository to your pom.xml:

<pluginRepositories>
    <pluginRepository>
        <id>fourthline-repo</id>
        <url>http://4thline.org/m2</url>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </pluginRepository>
</pluginRepositories>

Next, start Lemma by executing the manual goal of the plugin:

myproject/$ mvn clean org.fourthline.lemma:lemma-maven-plugin:manual

You can now open your generated documentation in target/manual/myproject-manual.xhtml, use a webbrowser to display this file.

If you want to know more, or if you are not using Maven, please continue reading the Lemma User Manual.

Lemma is Free Software, distributed under the terms of the GNU Affero General Public License.

org.fourthline.lemma:lemma:1.1.1

Creative Commons License