• Share
  • Email
  • Embed
  • Like
  • Save
  • Private Content
Documentando con Maven
 

Documentando con Maven

on

  • 1,202 views

This presentation describes how support documentation with maven.

This presentation describes how support documentation with maven.

Statistics

Views

Total Views
1,202
Views on SlideShare
1,202
Embed Views
0

Actions

Likes
0
Downloads
5
Comments
0

0 Embeds 0

No embeds

Accessibility

Categories

Upload Details

Uploaded via as Adobe PDF

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment

    Documentando con Maven Documentando con Maven Presentation Transcript

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