Maven: Docbkx Plugin

Ronnyfriedland |

Mit Hilfe von DocBook lassen sich recht elegant Dokumentationen erstellen. Für Maven gibt da das Plugin docbkx-maven-plugin.

Die folgende Anpassung ist an der pom.xml notwendig, um das Plugin in das eigene Projekt einzubinden:

<build>
    <resources>
        <resource>
            <directory>src/main/docbkx</directory>
            <targetPath>${project.build.directory}/docbkx</targetPath>
            <filtering>true</filtering>
        </resource>
    </resources>
     <plugins>
        <plugin>
            <groupId>com.agilejava.docbkx</groupId>
            <artifactId>docbkx-maven-plugin</artifactId>
            <version>2.0.13</version>
            <executions>
                <execution>
                    <goals>
                        <goal>generate-html</goal>
                    </goals>
                    <id>create-html</id>
                    <phase>package</phase>
                </execution>
            </executions>
            <configuration>
                <sourceDirectory>${project.build.directory}/docbkx</sourceDirectory>
            </configuration>
        </plugin>
     </plugins>
</build>
Mit dieser Konfiguration kann man auch die Tokenersetzung von Maven nutzen und ggf. die Version, Projektname in der Dokumentation ersetzen lassen.
Die XML - Datei mit der Dokumentation legt man unter src/main/docbkx ab, damit sie beim Bauen gefunden wird.

Sofern man Bilder in die Dokumentation einbinden will, so müssen diese, sofern die Dokumentation im HTML - Format generiert werden soll, mit in das Target - Verzeichnis kopiert werden. Dazu fügt man die folgenden Zeilen in der Konfiguration hinzu:

<configuration>
 ...
 <preProcess>
    <copy todir="${project.build.directory}/docbkx/html/img">
       <fileset dir="src/main/docbkx/img" />
    </copy>
 </preProcess>
 ...
</configuration>

Dann können die Bilder mit relativer Pfadangabe referenziert werden.