sphinx-maven-plugin

Maven plugin that creates the site with Sphinx

License	BSD License
Categories	Maven Build Tools
GroupId	io.airlift.maven.plugins
ArtifactId	sphinx-maven-plugin
Last Version	2.1
Release Date	Dec 30, 2018
Type	maven-plugin
Description	sphinx-maven-plugin Maven plugin that creates the site with Sphinx
Project URL	https://github.com/airlift/sphinx-maven-plugin
Source Code Management	https://github.com/airlift/sphinx-maven-plugin

Download sphinx-maven-plugin

Filename	Size
sphinx-maven-plugin-2.1.pom
sphinx-maven-plugin-2.1.jar	14 MB
sphinx-maven-plugin-2.1-sources.jar	14 MB
sphinx-maven-plugin-2.1-javadoc.jar	28 KB

How to add to project

Apache Maven

<plugin>
    <groupId>io.airlift.maven.plugins</groupId>
    <artifactId>sphinx-maven-plugin</artifactId>
    <version>2.1</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.0.5
org.apache.maven : maven-plugin-descriptor	jar	2.2.1
org.apache.commons : commons-compress	jar	1.9
commons-io : commons-io	jar	1.3.2
org.python : jython-standalone	jar	2.7.1

provided (1)

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

test (4)

Group / Artifact	Type	Version
io.takari.maven.plugins : takari-plugin-testing	jar	2.7.0
io.takari.maven.plugins : takari-plugin-integration-testing	pom	2.7.0
junit : junit	jar	4.12
com.google.guava : guava	jar	18.0

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:

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

   Maven 3 changes how reporting plugins are specified. A profile can be used to generate a pom.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/

4. Generate the documentation by running

   mvn site
   

   This will generate the documentation in the target/site folder.

TODOs

• Add a goal that bootstraps the documentation
• Document integration with other reporting plugins

Versions

Version
2.1 Dec 30, 2018
2.0 Nov 13, 2016