Skip to content
☕ Doclet that generates YAML files from Javadoc output for DocFX consumption.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
sandbox
src
.gitignore
LICENSE
README.md
intellij-java-google-style.xml
pom.xml

README.md

JavaDoc Doclet for DocFX

Build status

This doclet is designed to produce a YAML representation of the Javadoc-generated documentation, that can be integrated into DocFX.

Getting started

The easiest way is to just get the JAR files directly from our releases.

Alternatively, you can clone the repository and build it with the help of Maven. You can do so by calling:

mvn compile

Once the compilation is complete, you will need to generate a JAR file, that can be used alongside javadoc. You can do so by calling:

mvn package

This will produce two JAR files that you can use - one with dependencies, and another one without.

Usage

With maven-javadoc-plugin

When there is an existing java project where Maven is used as a build tool, one could add maven-javadoc-plugin to the root pom.xml:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
  <version>3.0.1</version>
  <configuration>
    <doclet>com.microsoft.doclet.DocFxDoclet</doclet>
    <docletArtifact>
      <groupId>${project.groupId}</groupId>
      <artifactId>${project.artifactId}</artifactId>
      <version>${project.version}</version>
    </docletArtifact>
    <useStandardDocletOptions>false</useStandardDocletOptions>
    <additionalOptions>-outputpath ./generated-files</additionalOptions>
    <!-- Add additional options here when needed -->
  </configuration>
</plugin>

The doclet can then be ran with the following command:

mvn javadoc:javadoc

The generated files will be placed in the ./target/site/apidocs/generated-files folder

Standalone

One can execute the javadoc command with the command line parameters:

javadoc \
-encoding UTF-8 \
-docletpath ./target/docfx-doclet-1.0-SNAPSHOT-jar-with-dependencies.jar \
-doclet com.microsoft.doclet.DocFxDoclet \
-classpath <list of jar with dependencies> \
-sourcepath ./src/test/java \
-outputpath ./target/test-out \
-excludepackages com\.msdn\..*:com\.ms\.news\..*  \
-excludeclasses .*SomeClass:com\.ms\..*AnyClass \
-subpackages com.microsoft.samples
Parameter Description
encoding Encoding for source files (optional).
docletpath Path to the doclet JAR file.
doclet Doclet class name.
classpath List of dependencies to be included in the classpath (optional).
sourcepath Location of the source code that needs to be documented.
outputpath The location for the generated YAML files.
excludepackages List of excluded packages, separated by a colon (:) (optional).
excludeclasses List of excluded classes, separated by a colon (:) (optional).
subpackages Subpackages to recursively load, separated by a colon (:).

For example, if we would want to generate documentation for JUnit-4.12 source code, we would need to account for the fact that the library depends on hamcrest-core-1.3, therefore we would download this library, unpack the sources JAR and run the following command:

javadoc \
-encoding UTF-8 \                                     # Source files encoding
-docletpath ./docfx-doclet-1.0-SNAPSHOT-jar-with-dependencies.jar \     # Set path to jar with doclet
-doclet com.microsoft.doclet.DocFxDoclet \            # Set name of doclet class
-cp ./hamcrest-core-1.3.jar \                         # Put dependencies into classpath
-sourcepath ./junit-4.12-sources \                    # Set localtion of jar with sources 
-outputpath ./test-out \                              # Set location of output files
-subpackages org:junit                                # Subpackages to recursively load separated by ':'

You can take a look at an example documentation generation script outlining the process above.

Development

When making changes, it is important to ensure that you are using DocletRunner class - it is responsible for makeing the javadoc call and takes params from an external configuration file.

To use it:

  • Create Run/Debug IDE configuration with the main class set as com.microsoft.doclet.DocletRunner
  • Add src\test\resources\test-doclet-params.txt as program arguments of configuration

Now we could run/debug doclet against source code classes located in the com.microsoft.samples package, as specified in the test-doclet-params.txt config file.

Serving DocFx documentation

  1. Get DocFX. You can read about it on the official site.
  2. Initialize an empty docset, by calling: docfx init -q
  3. Place the generated YAML files in the api folder in the generated docset.
  4. Build the content in the folder by calling: docfx
  5. Serve the content on a local web server: docfx serve _site
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.