The sphinx-maven
plugin is a Maven site plugin that uses
Sphinx to generate the main documentation. Sphinx itself is a tool to generate
documentation out of reStructured Text source files.
-
Create a folder
src/site/sphinx
(this can be changed via options should you want a different folder). -
Generate documentation in it. Basically what you need is
- A configuration file called conf.py that defines the theme and other options (such as which output formats etc.)
- The documentation files in reStructured Text format
- Additional files such as static files (images etc.), usually in a
_static
sub directory - Optionally, a customized theme in a sub directory called
_theme
For good examples of documentation, see Sphinx' examples page. Personally, I like Werkzeug (documentation source is on github) and Celery (documentation is also on github).
-
Add the sphinx maven plugin to your
pom.xml
:<reporting> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-project-info-reports-plugin</artifactId> <version>2.4</version> <reportSets> <reportSet> <reports></reports> </reportSet> </reportSets> </plugin> <plugin> <groupId>io.airlift.maven.plugins</groupId> <artifactId>sphinx-maven-plugin</artifactId> <version>1.0</version> </plugin> </plugins> </reporting>
It is important that you set the
reportSet
attribute of theproject-info-reports
plugin to an empty set ofreports
. If not then the defaultabout
report will be generated which conflicts with thesphinx-maven
plugin.Maven 3 changes how reporting plugins are specified. A
profile
can be used to generate apom.xml
that can be used with both Maven 2 and Maven 3:<profiles> <profile> <id>maven-3</id> <activation> <file> <!-- This employs that the basedir expression is only recognized by Maven 3.x (see MNG-2363) --> <exists>${basedir}</exists> </file> </activation> <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-site-plugin</artifactId> <version>3.0-beta-3</version> <configuration> <reportPlugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-project-info-reports-plugin</artifactId> <version>2.2</version> <reportSets> <reportSet> <reports></reports> </reportSet> </reportSets> </plugin> <plugin> <groupId>io.airlift.maven.plugins</groupId> <artifactId>sphinx-maven-plugin</artifactId> <version>1.0</version> </plugin> </reportPlugins> </configuration> </plugin> </plugins> </build> </profile> </profiles>
The profile will only be activated if Maven 3 is used to generate the site. For more details about Maven 3 and the site plugin see https://cwiki.apache.org/MAVEN/maven-3x-and-site-plugin.html and http://whatiscomingtomyhead.wordpress.com/2011/06/05/maven-3-site-plugin-how-to/
-
Generate the documentation by running
mvn site
This will generate the documentation in the
target/site
folder.
- Add a goal that bootstraps the documentation
- Document integration with other reporting plugins