Skip to content
Maven site plugin that uses Sphinx
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src
.gitignore
LICENSE
LICENSE.sphinx
README.md
pom.xml

README.md

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>org.tomdz.maven</groupId>
     		      <artifactId>sphinx-maven-plugin</artifactId>
     		      <version>1.0.2</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>org.tomdz.maven</groupId>
                             <artifactId>sphinx-maven-plugin</artifactId>
                             <version>1.0.2</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
You can’t perform that action at this time.