• 设为首页
  • 点击收藏
  • 手机版
    手机扫一扫访问
    迪恩网络手机版
  • 关注官方公众号
    微信扫一扫关注
    公众号

tomdz/sphinx-maven: Maven site plugin that uses Sphinx

原作者: [db:作者] 来自: 网络 收藏 邀请

开源软件名称(OpenSource Name):

tomdz/sphinx-maven

开源软件地址(OpenSource Url):

https://github.com/tomdz/sphinx-maven

开源编程语言(OpenSource Language):

Java 70.7%

开源软件介绍(OpenSource Introduction):

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



鲜花

握手

雷人

路过

鸡蛋
该文章已有0人参与评论

请发表评论

全部评论

专题导读
热门推荐
阅读排行榜

扫描微信二维码

查看手机版网站

随时了解更新最新资讯

139-2527-9053

在线客服(服务时间 9:00~18:00)

在线QQ客服
地址:深圳市南山区西丽大学城创智工业园
电邮:jeky_zhao#qq.com
移动电话:139-2527-9053

Powered by 互联科技 X3.4© 2001-2213 极客世界.|Sitemap