Docufier

Docufier is here to fulfil the age-old promise that your tests can be used as documentation.

It turns doc-commented JUnit test cases into markdown files, that expain how to use your code.

It offers several benefits:

• Share code between documentation and tests.
• Ensures examples are always syntactically and functionally correct.
• Helps focusing on the user of the code when writing tests.
• IDE support for writing documentation examples.
• Simplifies keeping documentation up-to-date (at least if you are in the habit of writing tests for features).

Getting Started

Step 1: Annotate Test Case

/** [DOC file=README.md]     
    The Cool-Library
    ================
*/

public class CoolTestSuite {

    /**    
    ### First step
    
    We can easily create a new cool using a "constructor" and get
    a really cool cool. 
    */ 
    
    @Test
    public void ensureANewCoolIsNotHot() {
        Cool cool = new Cool();
        assertTrue(cool.getTemperature() < 5);
    }

    /**
    [NO-DOC]
    Sometimes we write a test that is not really instructional.
    */
    @Test
    public void ensureEqualityWorks() {
        Cool oneCool = new Cool();
        Cool anotherCool = new Cool();

        assertEquals(oneCool, anotherCool);
    }

}

Step 2: Run docufier

new Docufier("src/test/java", "target/doc");

Will yield a file README.md in target/doc that looks like this

The Cool-Library
================

### First step

We can easily create a new cool using a "constructor" and get
a really cool cool.

~~~ .java
Cool cool = new Cool();
assertTrue(cool.getTemperature() < 5);         
~~~

How to run Docufier

Docufier can either be run directly from Java code or as part of a maven build using the docufier-plugin.

Running from Java

Include docufier as a dependency, e.g. using maven:

<dependency>
    <groupId>org.buildobjects</groupId>
    <artifactId>docufier</artifactId>
    <version>0.1.3</version>
</dependency>

Instantiate a new docufier instance, with the (test) source directory and the target directory:

new Docufier("src/test/java", "target/doc");

Running as part of your Maven Build

To run docufier in the generate-resources phase add the following to the pom.xml:

<build>
    <plugins>

        <plugin>
            <groupId>org.buildobjects</groupId>
            <artifactId>docufier-plugin</artifactId>
            <version>0.1.3</version>
            <executions>
                <execution>
                    <phase>generate-resources</phase>
                    <goals>
                        <goal>docufy</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Per default the plugin tries to read test cases from src/test/java and writes to target/doc.

These directories can be configured by adding a configuration element to the plugin element:

<configuration>
    <outputDirectory>src/test/java</outputDirectory>
    <outputDirectory>target/md</outputDirectory>
</configuration>