How to use it

Compile from Source Code

You will need to have JDK 11 or JDK 17 installed.

Maven

git clone https://github.com/manticore-projects/xml-doclet.git
cd xml-doclet
mvn install

Gradle

git clone https://github.com/manticore-projects/xml-doclet.git
cd xml-doclet
gradle publishToMavenLocal

Build Dependencies

Maven Release

<dependency>
    <groupId>com.manticore-projects.tools</groupId>
    <artifactId>xml-doclet</artifactId>
    <version>1.3.0</version>
</dependency>

Maven Snapshot

<repositories>
    <repository>
        <id>sonatype-snapshots</id>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
        <url>https://oss.sonatype.org/content/groups/public/</url>
    </repository>
</repositories>
<dependency>
    <groupId>com.manticore-projects.tools</groupId>
    <artifactId>xml-doclet+</artifactId>
    <version>1.4.0-SNAPSHOT</version>
</dependency>

Gradle Stable

repositories {
    mavenCentral()
}

dependencies {
    implementation 'com.manticore-projects.tools:xml-doclet:1.3.0'
}

Gradle Snapshot

repositories {
    maven {
        url = uri('https://oss.sonatype.org/content/groups/public/')
    }
}

dependencies {
    implementation 'com.manticore-projects.tools:xml-doclet:1.4.0-SNAPSHOT'
}

Sphinx Integration

Gradle

build.gradle

configurations {
    xmlDoclet
}

repositories {
    mavenCentral()
    // use Snapshots
    maven {
        url = uri('https://oss.sonatype.org/content/repositories/snapshots')
    }
}

dependencies {
    xmlDoclet 'com.manticore-projects.tools:xml-doclet:+'
}

tasks.register('xmldoc', Javadoc) {
    source = sourceSets.main.allJava

    // beware: Gradle deletes this folder automatically and there is no switch-off
    destinationDir = reporting.file("xmlDoclet")
    options.docletpath = configurations.xmlDoclet.files.asType(List)
    options.doclet = "com.github.markusbernhardt.xmldoclet.XmlDoclet"

    // optional: transform into Restructured Text for Sphinx
    options.addBooleanOption("rst", true)
    options.addBooleanOption("withFloatingToc", true)
    options.addStringOption("basePackage", "com.github.markusbernhardt.xmldoclet")

    // optional: copy the generated RST file into the Sphinx Folder
    doLast {
        copy {
            from reporting.file("xmlDoclet/javadoc.rst")
            into "${projectDir}/src/site/sphinx"
        }
    }
}

Maven

pom.xml

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <executions>
        <execution>
            <id>xml-doclet</id>
            <phase>prepare-package</phase>
            <goals>
                <goal>javadoc</goal>
            </goals>
            <configuration>
                <doclet>com.github.markusbernhardt.xmldoclet.XmlDoclet</doclet>
                <additionalparam>-d ${project.build.directory} -filename ${project.artifactId}-${project.version}-javadoc.xml</additionalparam>
                <useStandardDocletOptions>false</useStandardDocletOptions>
                <docletArtifact>
                    <groupId>com.manticore-projects.tools</groupId>
                    <artifactId>xml-doclet</artifactId>
                    <version>1.3.0</version>
                </docletArtifact>
            </configuration>
        </execution>
    </executions>
</plugin>

Floating Table of Content

Download the CSS file floating_toc.css and JavaScript file floating_toc.js and add those to your Sphinx resource folder _static:

Static Binaries Direct Download Links

File	Size
floating_toc.css	(2 kB)
floating_toc.js	(4 kB)

config.py

html_static_path = ['_static']
html_css_files = ['floating_toc.css']
html_js_files = ['floating_toc.js',]

Then you can provide the Floating TOC Option together with the Restructured Text Option in your build file:

build.gradle

tasks.register('xmldoc', Javadoc) {
    // optional: transform into Restructured Text for Sphinx
    options.addBooleanOption("rst", true)
    options.addBooleanOption("withFloatingToc", true)
    options.addStringOption("basePackage", "com.github.markusbernhardt.xmldoclet")

}