domingo, 30 de agosto de 2009

Crear documentación en Java: JavaHelp, DocBook y Ant

Recientemente, para un mini proyecto personal realizado en Java y Swing, necesité integrar un sistema de ayuda.
Help Wanted
Naturalmente pensé en el sistema estándar y predeterminado de Java para Swing: JavaHelp. Este nos permite crear un sistema de ayuda completo con tabla de contenidos, secciones, buscador y todas las funciones que esperamos encontrar. Incluye un SDK para el desarrollo, visualizadores, ejemplos y hasta puede extenderse para personalizarse si lo deseamos. Como está implementado 100% en Java, automáticamente está disponible para todas las plataformas.

Aunque lo conocía de antes, hasta el momento nunca había tenido oportunidad de usarlo, así que era una buena excusa para incursionar en el tema. Pero me encontré con un pequeño problema: no me parecía del todo útil aprender otro lenguaje de marcado, cuando encima solo podría generar como resultado archivos de ayuda en dicho formato. Estaba pensando en usar algo más universal, que pudiera generar salidas al menos en pdf y html, además del formato JavaHelp.

Una de las mejores alternativas, si no la mejor, es DocBook, que es el lenguaje XML específico para crear documentación en general y que cumple con todos los requisitos. Es un estándar muy usado para ello. Desde DocBook tenemos todas las opciones posibles para exportar a cualquier otro formato de salida, incluído JavaHelp, CHM, PDF, HTML (simple y multipágina), XML-FO y muchos más. Les enlazo una introducción en castellano a DocBook, en la cual pueden encontrar el siguiente diagrama:

DocBook es una especificación abierta, implementada y soportada por distintas herramientas. Hasta existen editores visuales para escribir documentos en este formato, por si no queremos aprender el lenguaje de marcado. Es muy conocido y utilizado en el entorno GNU/Linux.

Pero para completar el círculo, el desarrollador en mi pedía automatizar el proceso. Investigando un poco más, busqué información hasta lograr armar el conjunto de herramientas adecuado. No hay mucha información al respecto, no al menos de forma completa. Terminé usando un script de ANT desde Eclipse 3.5 Galileo, con un archivo fuente XML en DocBook, y con el soporte de varias librerías, ya me permite generar toda la documentación completa tanto en JavaHelp como en HTML, y eventualmente en cualquier otro formato. Probablemente agregue PDF y tal vez CHM.

El mejor y más completo tutorial que encontré es "Build DocBook XML in Eclipse". Hay que seguirlo al pie de la letra. Tiene un dato clave que es que la implementación Xalan/Xerces proporcionada por ANT en Eclipse no funciona debido a un bug, y debe ser reemplazarla por la última versión estable. Por supuesto, tuve ese problema :D. También fueron útiles en cierta medida los artículos "Creating an Online Help System with JavaHelp and DocBook" y "DocBook with Eclipse - Tutorial", que aportan algunos detalles más.

Aunque se supone que generar archivos de ayuda y documentación debería ser una tarea bastante habitual para todos los programadores, la ausencia de buenos tutoriales y algunas herramientas actualizadas que faciliten la tarea demuestran que no es tan así. Al final termino confirmando esa sensación de que es un ítem bastante olvidado. Ojalá sirvan estas lineas para facilitar la implementación de esta funcionalidad tan importante, tantas veces descuidada.

2 comentarios :

Miguel Fiandor dijo...

Aún no me he puesto a trastear con DocBook, pero se agradece mucho que hayas escrito sobre la existencia de varias posibilidades. También me toca buscar si existe algo par integrar DocBook en Netbeans, en vez de Eclipse...
Gracias

gorlok dijo...

Muchas gracias por el comentario. Intenté documentar lo mejor posible la combinación de herramientas que usé, porque si bien hay alguna documentación dando vueltas, está un poco dispersa. A medida que gane experiencia con DocBook iré compartiendo mis aventuras. Si bien en este proyecto no usé Netbeans, también lo uso de tanto en tanto. Si se presenta la oportunidad de replicarlo con Netbeans, comentaré los pasos necesarios y las diferencias. Un saludo.