Question

I set up the docbkx-maven-plugin to generate PDF documentation for a source project. In the parent pom I specified the version to be used as well as the reference to the docbook version to use:

<build>
<pluginManagement>
    <plugins>
        <plugin>
            <groupId>com.agilejava.docbkx</groupId>
            <artifactId>docbkx-maven-plugin</artifactId>
            <version>2.0.14</version>
            <dependencies>
                <dependency>
                    <groupId>net.sf.docbook</groupId>
                    <artifactId>docbook-xml</artifactId>
                    <version>5.0-all</version>
                    <type>zip</type>
                    <classifier>resources</classifier>
                    <scope>runtime</scope>
                </dependency>
            </dependencies>
        </plugin>
    </plugins>
</build>
</pluginManagement>

In the actual project I use the configuration:

<build>
<plugins>
<plugin>
    <groupId>com.agilejava.docbkx</groupId>
    <artifactId>docbkx-maven-plugin</artifactId>
    <executions>
        <execution> 
            <id>usersmanual</id>
            <phase>generate-resources</phase>
            <goals>
                <goal>generate-pdf</goal>
            </goals>
            <configuration>
                <includes>${basedir}/UserManual/*.xml</includes>
                <includes>${basedir}/UserManual/src/*.xml</includes>
                                <targetDirectory>${project.build.directory}/UserManual</targetDirectory>
                <chunkedOutput>true</chunkedOutput>
            </configuration>
        </execution>
    </executions>
</plugin>
</plugins>
</build>

No matter what goal(s) I specify or what includes I provide, the plugin performs no(!) operation. There is no target directory created and I do not see any meaningful output on the command line. The result looks like:

[INFO] --- docbkx-maven-plugin:2.0.14:generate-pdf (usersmanual) @ documentation ---
[INFO]

I use Maven 3.0.3.

What do I miss here? Is there any configuration not provided, yet, which will start the plugin to do some work?

UPDATE:
This is what I have now:

<plugin>
    <groupId>com.agilejava.docbkx</groupId>
    <artifactId>docbkx-maven-plugin</artifactId>
    <version>2.0.14</version>
    <dependencies>
        <dependency>
            <groupId>net.sf.docbook</groupId>
            <artifactId>docbook-xml</artifactId>
            <version>5.0-all</version>
            <type>zip</type>
            <classifier>resources</classifier>
        </dependency>
    </dependencies>
    <executions>
        <execution>
            <goals>
                <goal>generate-pdf</goal>
            </goals>
            <phase>prepare-package</phase>
            <configuration>
                <sourceDirectory>${project.basedir}/UserManual</sourceDirectory>
                <xincludeSupported>true</xincludeSupported>
                <includes>${project.basedir}/UserManual/UserManual.xml</includes>
                <includes>${project.basedir}/UserManual/**/*.xml</includes>
                <targetDirectory>${project.build.directory}/UserManual</targetDirectory>
            </configuration>
        </execution>
    </executions>
</plugin>

At least the directory target/Usermanual is greated, but it is still empty. Why is there still not output? Do I have a chance to get a meaningful log file from docbkx? mvn … -X does not tell much.

Answer 1

Your latest example contains two includes configuration options which is not valid maven configuration.

My recommendation is to stop trying to override all these defaults and accept the default location for the docbook source xml, at least initially while you get comfortable with the plugin and can diagnose what issues are from what changes.

Anyway, your <includes> should be just the root xml file of the documentation you’re trying to generate as it exists in the <sourceDirectory>. You do not need to include all of the xml files, you instead need to follow the xincludes approach since you’re declaring its usage. There are a number of projects using this mechanism that you can review and copy the usage of.

Ours is: https://github.com/jetty-project/jetty-documentation

We have a bit more complex usage since we use the maven filtering plugin to avoid having to mess with entities and the like. Getting back to your includes usage, if your top level docbook file is index.xml then your includes would simply be:

<includes>index.xml</includes>

No expressions or globs needed, you bring in the other xml documents with the <xi:include> tags where needed.