Skip to content
This repository has been archived by the owner on Aug 4, 2020. It is now read-only.
forked from tomdz/sphinx-maven

Maven site plugin that uses Sphinx

License

Unknown, Unknown licenses found

Licenses found

Unknown
LICENSE
Unknown
LICENSE.sphinx
Notifications You must be signed in to change notification settings

airlift/sphinx-maven-plugin

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

90 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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

About

Maven site plugin that uses Sphinx

Resources

License

Unknown, Unknown licenses found

Licenses found

Unknown
LICENSE
Unknown
LICENSE.sphinx

Stars

Watchers

Forks

Packages

No packages published

Languages

  • Java 69.2%
  • HTML 12.8%
  • Python 9.3%
  • Shell 8.7%