Creating documentation with maven

ⅰ亾dé卋堺 提交于 2019-12-04 04:35:06

I recently implemented the project documentation for my maven multi-module project using docbook and the docbkx plugin for maven. I now have it automatically generating html and pdf files every time I build the project site. I think docbkx really rocks, so I would suggest you use that.

Its true -you can create a very nice site just using the maven site and doxia plugins. In fact I'm using those two to generate my project site, But doxia support for docbook is very limited and doesn't let you modularize documentation, including parts of documents in a main document, for instance. So for the big reference-manuals I'm using docbkx.

If you want to take a peek, my project is here. You can actually download the source and see the nitty gritty of it. And, of course, if you have any question regarding this setup, i'll be more than glad to help.

Cheers Carlos

DocBook is one of the many supported inputs to Doxia, the engine used to generate docs by maven. Refer here: http://maven.apache.org/doxia/modules/index.html

In fact, the Doxia site answers your exact question: http://maven.apache.org/doxia/book/index.html

You can easily create a site (that contains documentation) with Maven using the mvn site command (i.e. using the plugin site).

This plugin creates technical reports (such as Javadoc, Unit tests reports, code coverage...) but can be also used to create a "real site". You have more details about that in this page.

Basically, you write your page using APT (Almost Plain Text which is quite simple to understand), or a XML-based format, Xdoc.

2 years ago, I create a complete user guide for one application I developed, using the XDoc format and the Site Maven plugin. Globally, it was quite easy to create!

I hope this will help you!

I've been using with success the Maven plugin Docbkx. You should give it a try

Docbkx

You should definitely take a look at the Maven Docbkx Plugin. It probably fits your needs. Doxia's support of DocBook is -uhm- suboptimal. In fact, last time I tried it, it generated something new that - as far as I could tell - wasn't DocBook.

The Maven Docbkx Plugin that I'm referring to supports all the customizations of the world (through plugin parameters, or XSLT overrides, if you're into that) + it features some mechanisms to integrate it with the Maven build. (Such as processing instructions for including Maven pom properties into your documents.)

Note that the ambition is to have a plugin that prevents you from having to manually put together a processing chain yourselves. So this plugin will both do the transformation to FO, and transforming that to PDF.

Although the question is quite old I want to give an update on this. If you want to use LaTeX for your documentation you should use a maven plugin to generate the documentation. There are a couple of maven-plugins doing this but a lot of them are not maintained anymore. There is a new maven-plugin which requires none or less configuration to get it working and the generated PDF (or PS or DVI) can be published as artifact.

Have a look at: mathan-latex-maven-plugin

There is AFAIK no official or semi-official plugin that will process LaTeX or DocBook, but what you could do (besides using the aforementioned site plugin) is to configure the exec plugin to process your LaTeX/DocBook sources during the site lifecycle, i.e. at the same time that the project's website is built.

E.g., something like

<plugin>
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>exec-maven-plugin</artifactId>
  <executions>
    <execution>
    <id>latex</id>
    <goals>
      <goal>exec</goal>
    </goals>
    <phase>site</phase>
      <configuration>
          ...
      </configuration>
    </execution>
  </executions>
</plugin>
易学教程内所有资源均来自网络或用户发布的内容,如有违反法律规定的内容欢迎反馈
该文章没有解决你所遇到的问题?点击提问,说说你的问题,让更多的人一起探讨吧!