Cristóbal González AlmirónConsultor de desarrollo de proyectos informáticos. Su experiencia profesional se ha desarrollado en empresas como Compaq, HP, Mapfre, Endesa, Repsol, Universidad Autónoma de Madrid, en las áreas de Desarrollo de Software (Orientado a Objetos), tecnologías de Internet, Técnica de Sistemas de alta disponibilidad y formación a usuarios.

Ver todos los tutoriales del autor

Fecha de publicación del tutorial: 2007-06-28

Tutorial visitado 9.938 veces Descargar en PDF
Crear el sitio web de documentación del proyecto con Maven Site

Crear el sitio web de documentación del proyecto con Maven Site

 

Crear el sitio web de documentación del proyecto con Maven Site. 1

Resumen. 1

Introducción. 1

Requisitos. 2

Creación del módulo ILOTools con Maven. 2

Creación del site de documentación del proyecto. 2

Creación de las carpetas del sitio web. 2

Creando la documentación. 3

Procesando la documentación. 3

Probando el sitio web. 4

Organización de los ficheros del sitio. 5

Editando el contenido del sitio. 6

Editando el menú de nuestro sitio web. 6

Añadiendo nuestro logo. 6

Añadiendo elementos al menú. 8

Añadiendo documentos externos. 9

Añadiendo nuevas páginas al sitio en formato APT. 9

Añadiendo imágenes para las páginas APT. 11

Referencias. 12

Conclusión. 12

 

 

Resumen

Tutorial de cómo crear los sitios web de documentación del proyecto con Apache Maven, utilizando simples editores de texto y crear la documentación en un formato sencillo (apt) y diferenciable (al subirlo al control de versiones podremos ver fácilmente las diferencias y la evolución de la documentación).

Introducción

Cuando creamos un proyecto una parte importante consiste en generar la documentación del mismo. Cada vez más los entornos de desarrollo nos ayudan a realizar esta tarea, pero siempre queda una etapa final, que es el armazón de la documentación.

Ahora que estoy empezando a desarrollar un nuevo proyecto (lo tenía guardado en el cajón hace ya algunos años… je, je) voy a aprovechar para crear su sitio de documentación y además mostraros cómo lo hago de una forma sencilla. Para ello voy a utilizar el plugin Site del Apache Maven, que me facilitará mucho las cosas.

En realidad, este plugin sirve para crear sitios de documentación de cualquier tipo de proyecto (sí, incluso de no informáticos) y tiene una característica que lo hace realmente valioso, y es que el formato de los documentos es un típico formato WIKI, el APT. Estos formatos tienen una característica importante, y es que el texto es diferenciable, es decir, podemos ver las diferencias entre versiones del documento fácilmente, ya que no hay apenas códigos de control que lo enturbien.

Requisitos

  • Instalar Java JDKy Maven 2.0 en nuestro entorno de desarrollo
  • Podéis ver otros artículos de Maven en www.adictosaltrabajo.com, como el de proyectos Maven y JSF, que os darán una idea de cómo instalarlo y manejarlo.
  • Maven 2.0 se descarga de la página de maven.apache.org.

Creación del módulo ILOTools con Maven

Vamos a ponernos manos a la obra, por lo que voy a comenzar creando un proyecto en blanco Java al que añadiré la documentación.  Sí, he dicho bien, primero comienzo con la documentación y luego programo. No hace falta escribir toda la documentación del proyecto al principio, sólo las líneas generales, que nos ayudarán a no perdernos en el desarrollo.

 

 

Si el resultado es un “BUILDING SUCCESSFULL” iremos por buen camino.

Ahora se habrá creado la carpeta ilotools en nuestro espacio de trabajo. La carpeta tiene la organización típica de Maven.

 

Creación del site de documentación del proyecto

Creación de las carpetas del sitio web

El plugin archetype:create nos permite crear las carpetas origen de la documentación de nuestro sitio web.

 

 

Esto nos crea las carpetas correctas en nuestro sitio web de documentación

 

 

 

Creando la documentación

Para editar la documentación usaremos simples editores de texto, pues la documentación principalmente la generaremos mediante ficheros APT (Almost plain text files, casi texto simple). Este formato es un típico formato WIKI de texto plano, que genera HTML mediante el plugin de maven (mvn site).

 

Procesando la documentación

Para procesar la documentación usaremos el comando site de maven. Este comando crea en la carpeta target/site del proyecto todos los ficheros del sitio web de nuestro proyecto, a partir de las plantillas que hemos creado en la carpeta src/site.

 

 

Esto nos genera el sitio Web completo, en la carpeta target/site

 

Probando el sitio web

Para probar la web vamos a usar el plugin jetty que viene integrado en el Maven. Simplemente hacemos mvn site:run y esto cargará el servidor web local jetty y dejará el sitio listo para revisarlo.

 

 

Si todo va bien nos saldrá algo como:

 

 

Esto nos indica que se ha arrancado un servidor web en la dirección http://localhost:8080/index.html

 

Abrimos un navegador para comprobarlo:

 

 

Como vemos esto es una página por defecto, que luego deberemos modificar. Paramos el servidor con Ctrl-C (o similar) y haremos algunos cambios

 

 

Organización de los ficheros del sitio

 

Dentro de la carpeta src/site tendremos varios elementos;

  • El fichero site.xml es el descriptor del sitio web. Deberemos editarlo para configurar las páginas y el resto de la información del sitio.
  • En la carpeta apt se dejarán los ficheros con formato APT
  • En la carpeta Resources dejaremos los ficheros de recursos de nuestro sitio: imágenenes, iconos, documentos, ficheros en general y otras páginas html que no se transformarán mediante el plugin.

 

Podemos colocar dentro de subcarpetas los diferentes elementos, y luego usaremos URLs relativas para llegar a ellos.

Editando el contenido del sitio

 

Editando el menú de nuestro sitio web

El descriptor del sitio generado por el plugin archetype es muy simple. Contiene más o menos lo siguiente:

 

 

<?xml version="1.0" encoding="ISO-8859-1"?>

<project name="Maven">

  <bannerLeft>

    <name>Maven</name>

    <src>http://maven.apache.org/images/apache-maven-project.png</src>

    <href>http://maven.apache.org/</href>

  </bannerLeft>

  <bannerRight>

    <src>http://maven.apache.org/images/maven-small.gif</src>

  </bannerRight>

  <body>

    <links>

      <item name="Apache" href="http://www.apache.org/" />

      <item name="Maven 1.0" href="http://maven.apache.org/"/>

      <item name="Maven 2" href="http://maven.apache.org/maven2/"/>

    </links>

 

    <menu name="Maven 2.0">

      <item name="APT Format" href="format.html"/>

      <item name="FAQ" href="faq.html"/>

      <item name="Xdoc Example" href="xdoc.html"/>      

    </menu>

  </body>

</project>

 

Como vemos hay varias secciones:

  • Información general del proyecto, como el nombre del proyecto
  • Los banners del sitio web
  • Los enlaces a otras páginas de interés, en el apartado links.
  • El menú del sitio, con sus elementos.

Añadiendo nuestro logo

Para añadir el logo creamos la carpeta src/site/resources/images y copiamos la imagen que queramos usar como logo. Yo he partido de la imagen del apache maven, que he copiado de la url que tengo en el descriptor del sitio, y luego la editaré:

 

 

Edito la imagen con cualquier programa y la guardo con el nombre que me guste. Le he llamado mainlogo.png, y debemos modificar el site.xml:

 

<bannerLeft>

    <name>ILOTools</name>

    <src>images/mainlogo.png</src>

    <href>http://ilotools.sourceforge.net</href>

  </bannerLeft>

 

Guardamos los cambios y probamos el sitio con mvn site:run

 

 

Como vemos esto va tomando otro color. Sólo nos quedaría editar el de la derecha…

 

Añadiendo elementos al menú

Basta añadir nuevos elementos a la sección <menu>, que pueden ser incluso subelementos. Por ejemplo, voy a modificar el menú por defecto:

 

 

    <menu name="ILO Tools">

      <item name="Introduction" href="introduction.html"/>

      <item name="ILO binary format" href="ilobinformat.html" />

      <item name="ILO Tools">

        <item name="User Guide" href="ilotools/userguide.html"/>

        <item name="Designing ILO enabled apps"

          href="ilotools/designingiloapps.html"/>

        <item name="javaDoc" href="javadoc/index.html" />

      </item>

      <item name="FAQ" href="faq.html"/>

      <item name="Resources">

        <item name="Xdoc Example" href="xdoc.html"/>

        <item name="API ref. (pdf)" href="docs/apireference.pdf"/>

      </item>     

    </menu>

       

 

El resultado que nos muestra jetty es:

 

 

Al añadir los elementos de menú nos falta una cosa más: añadir el contenido. Como vemos, cada enlace del menú apunta a una página html: esta página la podemos genera bien con un fichero apt o con un documento externo (hay más opciones).

Añadiendo documentos externos

Los documentos externos, como pueden ser documentos Word los añadiremos en la carpeta src/site/resources directamente. Maven los copiará al sitio Web a la carpeta raíz, o en subcarpetas, si así lo organizamos. Este es el lugar adecuado para dejar información formateada (word, pdfs, imáges, etc).  En nuestro ejemplo he creado un enlace a un documento pdf , que habremos de crear en src/site/resources/docs, con nombre apiref.pdf.

Añadiendo nuevas páginas al sitio en formato APT

Para añadir nuevas páginas en formato APT simplemente crearemos archivos de texto simple con cualquier editor de texto y los dejaremos en la carpeta src/site/apt o en una de sus subcarpetas.

 

Vamos a crear un fichero apt de ejemplo. Abrimos el fichero index.apt en un editor de texto y escribimos lo siguiente:

 

 ------

 The ILO Tools project

 -----

 The ILO Tools Project

 -----

 

Official home of the ILO tools and the ILO format

 

  This is the official site of the ILO Tools and the ILO format.

 

What is ILO format

 

  ILO stands for Internet Labeled Objects. ILO is a general purpose

  binary format for interchangin of information. ILO is desigened like SML to

  let a reader to figure aout the main content of the object reading the labels

  of the information included in it.

 

Features of the ILO format

 

  The ILO format has a lot of advanteges:

  *Small obgects. The size of objects is small as possible.

  *Structured format. The ILO object has a structured format. 

 

ILO vs. XML

 

  ILO was designed with size and perfomance in mind.  

 

 

 

+-----+

 

Working...

 

Hay que tener cuidado con los espacios antes del comienzo de una línea, pues el formato APT los usa para distinguir los diferentes tipos de elementos. Ahora compilamos el sitio y lo probamos:

 

Añadiendo imágenes para las páginas APT

Las imágenes las añadiremos a la carpeta de resources, y luego haremos un enlace a ellas desde los documentos o ficheros apt de nuestro sitio web. Como prueba rápida vamos a añadir la imagen del logo a mitad de la página de inicio. Para ello modificamos el fichero index.apt de la siguiente forma:

 

What is ILO format

 

  ILO stands for Internet Labeled Objects. ILO is a general purpose

  binary format for interchangin of information. ILO is desigened like SML to

  let a reader to figure aout the main content of the object reading the labels

  of the information included in it.

 

[images/mainlogo.png] Logo

 

Features of the ILO format

 

Y el resultado es el siguiente:

 

 

Como vemos es fácil añadir elementos al fichero apt. En las referencias tenemos más información sobre este formato.

 

Referencias

 

Conclusión

En este tutorial hemos aprendido una técnica rápida para crear el sitio web de documentación de nuestro proyecto, que además se integra de manera sencilla con el ciclo de desarrollo, y que le da un aspecto bastante profesional al sitio Web.

A continuación puedes evaluarlo:

Regístrate para evaluarlo

Por favor, vota +1 o compártelo si te pareció interesante

Share |
Anímate y coméntanos lo que pienses sobre este TUTORIAL: