ftldoc - Maven Plugin

Maven plugin to extract documentation from FreeMarker macro libraries

License	MIT License
Categories	Maven Build Tools
GroupId	com.kstruct
ArtifactId	ftldoc-maven-plugin
Last Version	0.0.2
Release Date	Jan 27, 2018
Type	maven-plugin
Description	ftldoc - Maven Plugin Maven plugin to extract documentation from FreeMarker macro libraries
Project URL	https://github.com/mattsheppard/ftldoc
Source Code Management	http://github.com/mattsheppard/ftldoc/tree/master

Download ftldoc-maven-plugin

Filename	Size
ftldoc-maven-plugin-0.0.2.pom
ftldoc-maven-plugin-0.0.2.jar	25 KB
ftldoc-maven-plugin-0.0.2-sources.jar	13 KB
ftldoc-maven-plugin-0.0.2-javadoc.jar	32 KB

How to add to project

Apache Maven

<plugin>
    <groupId>com.kstruct</groupId>
    <artifactId>ftldoc-maven-plugin</artifactId>
    <version>0.0.2</version>
</plugin>

Dependencies

compile (2)

Group / Artifact	Type	Version
org.freemarker : freemarker	jar	2.3.26-incubating
org.apache.maven : maven-plugin-api	jar	3.3.9

provided (1)

Group / Artifact	Type	Version
org.apache.maven.plugin-tools : maven-plugin-annotations	jar	3.4

Project Modules

There are no modules declared in this project.

FTLDoc

Generates HTML documentation for FTL templates and macros.

• Original author: chaquotay
• Improvements: nguillaumin
• Changed to a maven plugin: msheppard

Usage

You'll need to run mvn install on this project to install the plugin locally (or deploy it to your local nexus), and then add something like the following to the pom.xml for the project in which you want it to generate documentation.

...
    <build>
        <plugins>
...
            <plugin>
                <groupId>freemarker</groupId>
                <artifactId>ftldoc-maven-plugin</artifactId>
                <executions>
                    <execution>
                        <id>generate-documentation</id>
                        <phase>compile</phase>
                        <goals>
                            <goal>generate-documentation</goal>
                        </goals>
                        <configuration>
                            <freemarkerFiles>
                                <freemarkerFile>${project.build.directory}/src/main/resources/example1.ftl</freemarkerFile>
                                <freemarkerFile>${project.build.directory}/src/main/resources/example2.ftl</freemarkerFile>
                            </freemarkerFiles>
                            <templateDirectory>${project.basedir}/src/main/resources/templates</templateDirectory>
                            <outputDirectory>${project.build.directory}/documentation</outputDirectory>
                         </configuration>
                     </execution>
                 </executions>
             </plugin>
...
        </plugins>
    </build>
...

Usage as CLI

(WIP)

Example:

mvn freemarker:ftldoc-maven-plugin:0.0.2-SNAPSHOT:generate-documentation -DoutputDirectory=./outputdir/  -DfreemarkerFiles=./src/main/webapp/templates/webftl/lib/auxiliar_functions.ftl

templateDirectory not should be necesary, but on my small test, I need to add it and point to a folder with a valid template files

Comment syntax

The comments to process must start with a <#--- tag (3 dashes). This is to mimic the Javadoc behaviour where a /* is a standard comment, but /** is a Javadoc comment.

Macro comments

The first sentence of the comment (until the first dot) will be used a short description in the summary table.

Macro parameters should be indicated using @param <name> <description>.

HTML is permitted within comments.

Example:

<#---
	Does fancy stuff.
	
	<p>And does it well !</p>
	
	@param fist The first parameter.
	@param second The second parameter, a <code>boolean</code>.
-->
<#macro MyMacro first="" second=false>
    ...
<#/macro>

You can use any @ tags you want such as @author, or @mytag. These tags will be parsed and available in the template on the macro or comment objects (i.e. macro.@author ...).

Global comment

A global comment for a given .ftl file can be written at the top of the file. The first comment found that isn't followed by a <#macro /> is considered the global comment.

Categories

Macro can be put in categories. To embed a group of macros in a category, use the @begin and @end tags.

<#-- @begin Menu handling -->

<#---
    ...
-->
<#macro MainMenu> ... </#macro>

<#---
    ...
-->
<#macro SubMenu> ... </#macro>

<#-- @end -->

Custom templates

The generated doco is based on FreeMarker templates. There is a default set of templates provided but you can use your own. To do so, use the -tpl </path/to/tpl/folder option. The folder must contains the following files:

• file.ftl : Used for a single .ftl file documentation.
• index.ftl : Index page (frameset).
• index-all-cat.ftl : Index of categories.
• index-all-alpha.ftl : Alphabetical index.
• overview.ftl : Overview (list of documented .ftl libraries).
• filelist.ftl : List of documented .ftl files (Left side of the frameset).

Versions

Version
0.0.2 Jan 27, 2018