El documento presenta tres opciones para documentación: Docs, Wikis y Maven. Luego se enfoca en Docbook y Maven Doxia, explicando que Docbook es un formato XML para documentación y que Maven Doxia es un framework para generar contenido estático usado extensamente en Maven. Finalmente, muestra un ejemplo práctico de cómo usar Maven Doxia para escribir documentación en formato wiki y publicarla estáticamente.

1. Documentando con Maven
28 de Abril de 2011
JUGAR Meetup, Buenos Aires
ldap://cn=Juan F. Codagnone, o=Zauber, dc=Argentina
http://juan.zaubersoftware.com/
http://twitter.com/juam
http://www.zaubersoftware.com

2. Agenda
01. Introducción
02. Docbook
03. Maven Doxia
03.
http://www.zaubersoftware.com 01|22

3. Doc & Maven
01.
Introducción
http://www.zaubersoftware.com 02|22

4. Doc & Maven
¿Que espero de un entorno de documentación?
• Facilidad de edición
• Facilidad para seguir los cambios
• Direccionabilidad a porciones de la documentación
http://www.zaubersoftware.com 03|22

5. Doc & Maven
Opción I: Docs o similares
• Dificultad para editar el archivo de forma liviana (editor
simple de texto)
• La comparación de cambios entre revisiones se hace con
herramientas custom (las mismas de edición)
o (no es tan amigable para el SCM)
• Poca direccionabilidad al interior del documento
• Es WYSIWYG
http://www.zaubersoftware.com 04|22

6. Doc & Maven
Opción II: Wikis
• Facilidad de Cambio
o ...pero tengo que estar online
• Facilidad para direccionar a partes de la doc (anchors)
• Facilidad de publicación
o está online
• Es más dificultoso de exportar a formatos lineales
o pdfs, words
o newbies se pierden en el grafo de documentos (vs guía
de referencia lineal)
• Cada motor wiki es un mundo
o Para obtener buenos resultado, seguramente requiere de
$$ en licencias
• En general no es WYSWYG
http://www.zaubersoftware.com 05|22

7. Doc & Maven
Opción III: Maven
• Documentación cerca del código
• Facilmente editable
• No es WYSWYG
• Dos tipos de documentaciones
o Estilo WIKI (grafo de documentos)
o Estilo Guía de referencia
http://www.zaubersoftware.com 07|22

8. Doc & Maven
02.
Docbook & Maven
http://www.zaubersoftware.com 08|22

9. Doc & Maven
Docbook: Intro
• http://www.docbook.org
• Formato basado en XML
o version 5 basado XSD
o version 4.x basado DTD
• Salida:
o PDF
o HTML único
o HTML
• Ejemplos de salida:
o Guía de referencia de Spring
o Guía de referencia de Hibernate
o Guía de referencia de Zauber Commons
http://www.zaubersoftware.com 09|22

10. Doc & Maven
Ejemplo salida HTML
http://www.zaubersoftware.com 10|22

11. Doc & Maven
Ejemplo salida PDF
http://www.zaubersoftware.com 11|22

12. Doc & Maven
Editando docbook desde el eclipse
http://www.zaubersoftware.com 12|22

13. Doc & Maven
Editando desde el eclipse: autocomplete
http://www.zaubersoftware.com 13|22

14. Doc & Maven
Configurando y ejecutando
• Se requiere un pom.xml con la configuración de plugins (es
bastante larga la configuración)
• Opcionalmente se puede tener un módulo de estilos para
cambiar el css y el formato de las salidas html y pdf
• Ejemplo: (basado en los proyectos de JBOSS)
– git clone https://github.com/zaubersoftware/commons­documentation
– cd commons­documentantion
– mvn ­n install # realizaremos la instalacion en varios pasos
– cd style # debido a un bug en el plugin
– mvn install
– cd ../reference # los fuentes están en en­US.
– mvn # un unico punto de entrada + includes
http://www.zaubersoftware.com 14|22

15. Doc & Maven
03.
Maven Doxia
http://www.zaubersoftware.com 15|22

16. Doc & Maven
Maven Doxia: Introducción
• http://maven.apache.org/doxia/
o "... Doxia is a content generation framework which aims to provide its users
with powerful techniques for generating static and dynamic content: Doxia can
be used in web-based publishing context to generate static sites..."
• Usado extensivamente dentro de maven
• Formatos:
o APT (Almost Plain Text) / XDoc / XHTML
o TWiki / Confluence / XWiki
o Simplified DocBook
o FML (FAQ Markup Language),
o FO, iText, LaTeX, RTF
• Genera archivos estáticos: Solo requiere servidor estático
de archivos en su publicación.
http://www.zaubersoftware.com 16|22

17. Doc & Maven
Maven Doxia: Sinks y Parser
• Útil para generar documentación programaticamente
• Parsers
o Leen un formato y emiten mensajes hacia los Sinks
 nueva sección
 nuevo parrafo
 empieza texto resaltado
• Sinks
o Recibe eventos y los traduce a un formato
• Ejemplo:
o Parser TWiki + Parser FML emiten a Sink XHTML
 Obtenemos un sitio web!
http://www.zaubersoftware.com 17|22

18. Doc & Maven
Maven Doxia In Action
Ejemplo
$ git clone https://github.com/zaubersoftware/garfio/
$ cd site
$ mvn site
$ firefox target/site/index.html
¿Qué ver?
● pom.xml (configuración de modulos extras en el plugin
site)
● src/site/site.xml (barra de navegación y skin)
● src/site/<parser>/fooo.<parser>
http://www.zaubersoftware.com 18|22

19. Doc & Maven
Maven Doxia In Action
http://www.zaubersoftware.com 19|22

20. Doc & Maven
Maven Doxia In Action: Escribimos en la wiki la doc
http://www.zaubersoftware.com 20|22

21. Doc & Maven
Maven Doxia In Action: Publicamos estaticamente
http://www.zaubersoftware.com 21|22

22. Doc & Maven
:-)
¿Preguntas?
http://www.zaubersoftware.com 22|22