Documentando con Maven

1,184 views

Published on

This presentation describes how support documentation with maven.

0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total views
1,184
On SlideShare
0
From Embeds
0
Number of Embeds
2
Actions
Shares
0
Downloads
7
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

Documentando con Maven

  1. 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/juamhttp://www.zaubersoftware.com
  2. 2. Agenda 01. Introducción 02. Docbook 03. Maven Doxia 03.http://www.zaubersoftware.com 01|22
  3. 3. Doc & Maven 01. Introducciónhttp://www.zaubersoftware.com 02|22
  4. 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. 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. 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. 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. 8. Doc & Maven 02. Docbook & Mavenhttp://www.zaubersoftware.com 08|22
  9. 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. 10. Doc & Maven Ejemplo salida HTMLhttp://www.zaubersoftware.com 10|22
  11. 11. Doc & Maven Ejemplo salida PDFhttp://www.zaubersoftware.com 11|22
  12. 12. Doc & Maven Editando docbook desde el eclipsehttp://www.zaubersoftware.com 12|22
  13. 13. Doc & Maven Editando desde el eclipse: autocompletehttp://www.zaubersoftware.com 13|22
  14. 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. 15. Doc & Maven 03. Maven Doxiahttp://www.zaubersoftware.com 15|22
  16. 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. 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. 18. Doc & Maven Maven Doxia In ActionEjemplo $ 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. 19. Doc & Maven Maven Doxia In Actionhttp://www.zaubersoftware.com 19|22
  20. 20. Doc & Maven Maven Doxia In Action: Escribimos en la wiki la dochttp://www.zaubersoftware.com 20|22
  21. 21. Doc & Maven Maven Doxia In Action: Publicamos estaticamentehttp://www.zaubersoftware.com 21|22
  22. 22. Doc & Maven :-) ¿Preguntas?http://www.zaubersoftware.com 22|22

×