sphinx-maven

Maven plugin that creates the site with Sphinx

License	BSD License
Categories	Maven Build Tools
GroupId	com.stratio.maven
ArtifactId	sphinx-maven-plugin
Last Version	2.0.0
Release Date	Jan 27, 2015
Type	maven-plugin
Description	sphinx-maven Maven plugin that creates the site with Sphinx
Project URL	http://www.stratio.com
Source Code Management	http://github.com/Stratio/sphinx-maven/tree/master

Download sphinx-maven-plugin

Filename	Size
sphinx-maven-plugin-2.0.0.pom
sphinx-maven-plugin-2.0.0.jar	9 MB
sphinx-maven-plugin-2.0.0-sources.jar	9 MB
sphinx-maven-plugin-2.0.0-javadoc.jar	45 KB

How to add to project

Apache Maven

<plugin>
    <groupId>com.stratio.maven</groupId>
    <artifactId>sphinx-maven-plugin</artifactId>
    <version>2.0.0</version>
</plugin>

Dependencies

compile (6)

Group / Artifact	Type	Version
org.apache.maven.reporting : maven-reporting-api	jar	3.0
org.apache.maven.reporting : maven-reporting-impl	jar	2.3
org.apache.maven.shared : maven-filtering	jar	1.3
org.apache.commons : commons-compress	jar	1.9
org.apache.commons : commons-io	jar	1.3.2
org.python : jython-standalone	jar	2.5.2

provided (1)

Group / Artifact	Type	Version
org.apache.maven.plugin-tools : maven-plugin-annotations	jar	3.4

Project Modules

There are no modules declared in this project.

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

1. Create a folder src/site/sphinx (this can be changed via options should you want a different folder).

2. 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).

3. 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 the project-info-reports plugin to an empty set of reports. If not then the default about report will be generated which conflicts with the sphinx-maven plugin.

4. 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.

STRATIO BIG DATA Inc.

Drive Digital Transformation through Big Data and AI with a unique product

Versions

Version
2.0.0 Jan 27, 2015