Introduction
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.
Basic Usage
-
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
:<build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-site-plugin</artifactId> <version>3.4</version> <configuration> <reportPlugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-project-info-reports-plugin</artifactId> <version>2.8</version> <reportSets> <reportSet> <reports></reports> </reportSet> </reportSets> </plugin> <plugin> <groupId>com.stratio.maven</groupId> <artifactId>sphinx-maven-plugin</artifactId> <version>2.0.0</version> <configuration> <builders> <entry>singlehtml</entry> </builders> <resources> <resource> <directory>src/site/sphinx</directory> <filtering>true</filtering> <includes> <include>conf.py</include> </includes> </resource> </resources> </configuration> </plugin> </reportPlugins> </configuration> </plugin> </plugins> </build>
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. -
Generate the documentation by running
mvn site
This will generate the documentation in the
target/site/[builder]
folder.
CHANGELOG
2.0.0
- Refactor all the code to easy add new improvements.
- Updated all libraries into pom file.
- Added resources filtering. Now you can put in your conf.py file this:
version = '${project.version}'
TODOs
- PDF generator only works with jpg not with png.
- Update Sphinx version.
- Improve Sphinx jar generator scripts.