Creando documentación con maven

Question

Estoy en el medio de revisitar maven. Nuestro equipo tuvo una mala experiencia la última vez que miramos esto, como lo fue durante el período en que maven estaba realizando una nueva configuración de 1.x a 2.x, por lo que muchas de las dependencias que necesitábamos no se habían trasladado a los nuevos repositorios. . Sin embargo, tengo tiempo para reconsiderar ahora.

Estoy interesado en el uso de Maven y látex o DocBook para la creación de documentación, y me preguntaba si alguien tenía alguna experiencia para compartir, estructura del proyecto/módulo, buenos plugins para utilizar, etc ...

Muchos gracias :-)

Editar:

Solo para aclarar, yo estaba buscando para escribir un artículo/libro técnico, y mi artefacto deseada sería probablemente un PDF.

Answer 1

Recientemente implementé la documentación del proyecto para mi proyecto multi-módulo maven usando docbook y el complemento docbkx para maven. Ahora lo tengo generando automáticamente archivos html y pdf cada vez que construyo el sitio del proyecto. Creo que docbkx realmente es una piedra, así que te sugiero que la uses.

Es verdad: puede crear un sitio muy agradable simplemente usando el sitio maven y los complementos de doxia. De hecho, estoy usando esos dos para generar el sitio de mi proyecto, pero el soporte de doxia para docbook es muy limitado y no le permite modularizar la documentación, incluyendo partes de documentos en un documento principal, por ejemplo. Entonces, para los grandes manuales de referencia, estoy usando docbkx.

Si quieres echar un vistazo, mi proyecto es here. En realidad puedes descargar la fuente y ver lo esencial de ella. Y, por supuesto, si tiene alguna pregunta con respecto a esta configuración, estaré más que contento de ayudarlo.

Saludos Carlos

Answer 2

Puede crear fácilmente un sitio (que contiene documentación) con Maven utilizando el comando mvn site (es decir, usando el plugin site).

Este complemento crea informes técnicos (como Javadoc, informes de pruebas unitarias, código de cobertura ...) pero también se puede usar para crear un "sitio real". Tiene más detalles al respecto en this page.

Básicamente, usted escribe su página utilizando APT (texto llano Casi que es bastante sencillo de entender), o un formato basado en XML, Xdoc.

Hace 2 años, creé una guía de usuario completa para una aplicación que desarrollé, utilizando el formato XDoc y el plugin Site Maven. ¡Globalmente, fue bastante fácil de crear!

Espero que esto te ayude!

Answer 3

AFAIK no tiene un complemento oficial o semioficial que procese LaTeX o DocBook, pero lo que podría hacer (además del uso del complemento de sitio mencionado anteriormente) es configurar el complemento ejecutivo para procesar sus fuentes LaTeX/DocBook durante el sitio. ciclo de vida, es decir, al mismo tiempo que se construye el sitio web del proyecto.

por ejemplo, algo así como

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

Answer 4

DocBook es una de las muchas entradas soportados a Doxia, el motor utilizado para generar documentos de experto. Consulte aquí: http://maven.apache.org/doxia/modules/index.html

De hecho, el sitio Doxia responde a su pregunta exacta: http://maven.apache.org/doxia/book/index.html

Answer 5

He estado usando con éxito el plugin Maven Docbkx. Usted debe darle una oportunidad

Docbkx

Answer 6

Definitivamente, usted debe echar un vistazo a la Maven Docbkx Plugin. Probablemente se ajuste a tus necesidades. El soporte de Doxia de DocBook es -uhm- subóptimo. De hecho, la última vez que lo intenté, generó algo nuevo que, por lo que pude ver, no era DocBook.

El complemento Maven Docbkx al que me refiero es compatible con todas las personalizaciones del mundo (a través de parámetros de complemento, o sobrescrituras XSLT, si se quiere) + cuenta con algunos mecanismos para integrarlo con la compilación Maven. (Como las instrucciones de procesamiento para incluir propiedades de Maven pom en sus documentos.)

Tenga en cuenta que la ambición es tener un complemento que evite tener que armar manualmente una cadena de procesamiento. Entonces, este complemento hará la transformación a FO y lo transformará en PDF.

Answer 7

Aunque la cuestión es bastante antiguo que quieren dar una actualización sobre esto. Si desea utilizar LaTeX para su documentación, debe usar un complemento maven para generar la documentación. Hay un par de plugins maven haciendo esto, pero muchos de ellos ya no se mantienen. Existe un nuevo plugin maven que no requiere configuración para ponerlo en funcionamiento y el PDF generado (o PS o DVI) se puede publicar como artefacto.

Tenga una mirada en: mathan-latex-maven-plugin