Documentando con Maven

Documentando con Maven

28 de Abril de 2011JUGAR Meetup, Buenos Aires

http://www.zaubersoftware.com

ldap://cn=Juan F. Codagnone, o=Zauber, dc=Argentina

http://juan.zaubersoftware.com/

http://twitter.com/juam

http://www.zaubersoftware.com/

http://juan.zaubersoftware.com/

http://twitter.com/juam

Agenda

Introducción

Docbook

Maven Doxia

01.

03.

01|22

02.

03.



Introducción

Doc & Maven

01.

02|22http://www.zaubersoftware.com


¿Que espero de un entorno de documentación?

Doc & Maven

03|22

• Facilidad de edición• Facilidad para seguir los cambios• Direccionabilidad a porciones de la documentación



Opción I: Docs o similares

Doc & Maven


• 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


Opción II: Wikis

Doc & Maven


• Facilidad de Cambioo ...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, wordso 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


Opción III: Maven

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


Docbook & Maven

Doc & Maven

02.



Docbook: Intro

Doc & Maven


• http://www.docbook.org• Formato basado en XML

o version 5 basado XSDo version 4.x basado DTD

• Salida:o PDFo HTML únicoo HTML

• Ejemplos de salida:o Guía de referencia de Springo Guía de referencia de Hibernateo Guía de referencia de Zauber Commons


http://www.docbook.org/

Ejemplo salida HTML

Doc & Maven



Ejemplo salida PDF

Doc & Maven



Editando docbook desde el eclipse

Doc & Maven



Editando desde el eclipse: autocomplete

Doc & Maven



Configurando y ejecutando

Doc & Maven


• 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/commonsdocumentation

– cd commonsdocumentantion

– 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 enUS.

– mvn # un unico punto de entrada + includes


https://github.com/zaubersoftware/commons-documentation

Maven Doxia

Doc & Maven

03.



Maven Doxia: Introducción

Doc & Maven


• 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 / XHTMLo TWiki / Confluence / XWikio Simplified DocBooko FML (FAQ Markup Language), o FO, iText, LaTeX, RTF

• Genera archivos estáticos: Solo requiere servidor estático de archivos en su publicación.


Maven Doxia: Sinks y Parser

Doc & Maven


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

• Sinkso Recibe eventos y los traduce a un formato

• Ejemplo:o Parser TWiki + Parser FML emiten a Sink XHTML

Obtenemos un sitio web!


Maven Doxia In Action

Doc & Maven


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>


Maven Doxia In Action

Doc & Maven



Maven Doxia In Action: Escribimos en la wiki la doc

Doc & Maven



Maven Doxia In Action: Publicamos estaticamente

Doc & Maven



¿Preguntas?

Doc & Maven

:-)



Documentando con Maven

Documents

Transcript of Documentando con Maven