source-extractor-maven-plugin

An opinionated little tool to extract code samples for inclusion in HTML or markdown to avoid maintaining example code separately from tests.

An example can be seen here: https://github.com/ethlo/itu/?tab=readme-ov-file#parsing

Standing on the shoulders of these awesome projects:

• https://github.com/javaparser/javaparser
• https://github.com/PebbleTemplates/pebble

How it works

You define the plugin to extract methods from classes in a given package. These are processed and then rendered with the specified template, and are available as a variable name matching the defined <source> name. This variable can then be used in maven resource interpolation to be included in a readme file, for example.

Usage

We need to set up the plugin to extract the relevant source code. I recommend a package with samples you want to showcase, like src/test/java/mysamples.

The example below stores a README.md template in src/site.

The pom.xml resources section (must be filtered) so that you can include snippets rendered.

<project>
    <build>
        <plugins>
            <plugin>
                <groupId>com.ethlo.documentation</groupId>
                <artifactId>source-extractor-maven-plugin</artifactId>
                <version>0.3.0</version>
                <configuration>
                    <template>src/main/site/github.template.md</template>
                    <sources>
                        <source>src/test/java/samples</source>
                    </sources>
                </configuration>
                <executions>
                    <execution>
                        <phase>initialize</phase>
                        <goals>
                            <goal>extract</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
        <resources>
            <resource>
                <directory>src/main/resources</directory>
            </resource>
            <resource>
                <filtering>true</filtering>
                <directory>${project.basedir}/src/main/site</directory>
                <includes>
                    <include>README.md</include>
                </includes>
                <targetPath>${project.basedir}</targetPath>
            </resource>
        </resources>
    </build>
</project>

Extracted samples

showOffFeatureA » source

Description of the cool feature A goes here!

final List<String> list = Arrays.asList("something", "cool");
assert list.size() == 2;
assert list != null;

showOffFeatureB » source

Description of the cool feature B goes here!

And some more here!

final List<String> list = Arrays.asList("something", "else", "cool");
assert list.size() == 2;
assert list != null;