The sphinx-maven plugin has these configuration options:
Parameter | Description | Default value |
---|---|---|
sourceDirectory | The directory containing the documentation source. | ${basedir}/src/site/sphinx |
outputDirectory | The directory where the generated output will be placed. | ${project.reporting.outputDirectory} |
fork | Whether to run Sphinx in a forked JVM instance. | false |
jvm | The JVM binary to use. If not set, then will use the one used to run the plugin. | |
argLine | Additional arguments for the forked JVM instance (such as memory options). | |
forkTimeoutSec | How long the plugin should wait for the plugin. 0 means wait forever. | 0 |
outputName | The base name used to create the report’s output file(s). | index |
name | The name of the report. | Documentation via sphinx |
description | The description of the report. | Documentation via sphinx |
builder | The builder to use. See the Sphinx commandline documentation for a list of possible builders. | html |
verbose | Whether Sphinx should generate verbose output. | true |
warningsAsErrors | Whether warnings should be treated as errors. | false |
force | Whether Sphinx should generate output for all files instead of only the changed ones. | false |
tags | Additional tags to pass to Sphinx. See the Sphinx tag documentation for more information. |
The sphinx-maven plugin has experimental support for PDF generation. You’ll turn it on by using the pdf builder, e.g.:
<plugin>
<groupId>org.tomdz.maven</groupId>
<artifactId>sphinx-maven-plugin</artifactId>
<version>1.0.3</version>
<configuration>
<builder>pdf</builder>
<outputDirectory>${project.reporting.outputDirectory}/pdf</outputDirectory>
</configuration>
</plugin>
You’ll likely also have to add some additional configuration options to your conf.py file (usually in src/site/sphinx) to tell the pdf builder what to do. At a minimum you’ll probably need to point it to the index page by adding this to the end:
# -- Options for PDF output ---------------------------------------------------
pdf_documents = [
('index', u'<file name>', u'<document name>', u'<author>'),
]
For additional options see the Sphinx section of the rst2pdf manual.
Sphinx is run via Jython which will generate lots of small classes for various Python constructs. This means that the plugin will use a fair amount of memory, especially PermGen space (a moderate plugin run will likely use about 80mb of PermGen space). Therefore we suggest to either run maven with at least 256mb of heap and 128mb of PermGen space, e.g.
MAVEN_OPTS=”-Xmx256m -XX:MaxPermSize=128m” mvn site
or use the fork parameter of the plugin, e.g.:
<plugin>
<groupId>org.tomdz.maven</groupId>
<artifactId>sphinx-maven-plugin</artifactId>
<version>1.0.3</version>
<configuration>
<fork>true</fork>
<argLine>-Xmx256m -XX:MaxPermSize=128m</argLine>
</configuration>
</plugin>