Tag Archives: Documentación

Documentar proyectos

Documentación

Hace unas semanas, hablaba de NgDocs para documentar nuestros proyectos AngularJS (enlace a entrada). Hoy os traigo 2 alternativas que me han parecido bastante dinámicas y basadas en escribir documentación en Markdown.

Una de ellas es Daux.io

Con Daux, escribiendo en markdown y distribución de carpetas tipo 0X_NAME_FOLDER y dentro de la misma 01_name_file.md, 0X_name_file.md, … podemos crear nuestro menú y jugando con los tags <hX> creamos los encabezados de cada apartado. Es bastante sencillo de usar. Con Grunt lanzas la tarea por defecto y verás la documentación en el puerto :8085.

Puedes configurar tu propio theme basado en bootstrap creando un nuevo template en la carpeta templates y un nuevo .less en la carpeta less Ej. daux-theme_name.less. En su Github (https://github.com/justinwalsh/daux.io) tienen ejemplos de proyectos que lo han usado y uno que lo ha customizado como http://docs.trackjs.com/

A todo esto, es necesario PHP para poder ver la documentación.

 Otra alternativa es Slate

Slate se comporta de forma similar a Daux, pero a diferencia de este, para definir un menú jerárquico, debemos jugar con los tags <hX>. Ej. # Title, es el título para un item del menú, ## Title es el título para el subitem del menú y ### Title es el título para encabezar los apartados en el documento. Puedes distribuir estos apartados por carpetas en includes pero deberás especificarlos en el index.md.

Una gran utilidad que tiene es el buscador, que viene genial para cuando nuestra documentación es muy grande y queremos dar con un apartado en particular.

Para un template nuevo, debemos editar los ficheros screen.css y print.css en la carpeta stylesheets.

Una de los proyectos que podemos ver en su Github (https://github.com/tripit/slate) que usan Slate para documentar es Travis CI un gran ejemplo de como podemos escribir nuestra documentación.

Con ambos escribimos en Markdown y podemos destacar códigos de ejemplos, trabajan de diferente manera, pero la decisión de cual usar es tuya.

Pues creo que hasta aquí todo. Creo que lo próximo será explicar una solución que hemos conseguido en Zyncro, totalmente automatizada y muy interesante para grandes proyectos.

tags: , , ,

Documentar nuestros proyectos AngularJS con NgDocs

AngularJS, Documentación, Javascript

Si estas trabajando en un proyecto AngularJS, supongo que te habrás topado con la idea de como documentar todo esto de forma automática al mas puro estilo JavaDoc o PHPDoc. Pues es lo que me preguntaba esta semana. Pues buscando, una alternativa sencilla a implementar ha sido NgDocs. NgDocs es un plugin para Grunt o Gulp que nos permite automatizar la generación de documentación mediante una tarea.

Yo tan solo voy a explicar como implementarla para Grunt aunque luego dejaré enlaces tanto para Gulp como para Grunt.

La instalación es muy sencilla:
npm install grunt-ngdocs --save-dev

Una vez hayamos instalado esto, hacemos los siguientes pasos:

Cargamos el plugin en nuestro Gruntfile.js: grunt.loadNpmTasks('grunt-ngdocs');

Y ahora, creamos la tarea:
ngdocs: {
   all: ['src/**/*.js']
}

Registramos la tarea:
grunt.registerTask( 'ngdocs' );

Ahora, para que NgDocs nos sepa describir para que es cada controlador, directiva y demás, deberemos escribir unos comentarios previos al código:

Ahora, ya podríamos lanzar un grunt ngdocs y nos tomará la información de todos los archivos .JS de nuestro proyecto donde tengamos estos comentarios y nos generará un directorio “docs” donde si vamos a http://localhost:port/docs podremos ver una documentación.

La vista que nos presentará es muy parecida a la de AngularJS. Podemos hacer pequeños ejemplos prácticos y también tiene un buscador lateral para hacer la búsqueda entre los apartados.

Para mas información, os dejo los enlaces del plugin en npm:
Grunt: https://www.npmjs.com/package/grunt-ngdocs
Gulp: https://www.npmjs.com/package/gulp-ngdocs

En ambos plugins tenéis un repositorio con un ejemplo e ir haciendo pruebas. En la misma documentación del paquete de npm, invitan a que miremos un artículo de como documentar proyectos en AngularJS https://github.com/angular/angular.js/wiki/Writing-AngularJS-Documentation.

En una próxima edición mostraré como poder documentar métodos y demás apartados que puedan ser útiles.

Nota:
Existe un proyecto, generador de documentación llamado Dgine, que es un tanto mas complejo de configurar y que aún no he probado, pero es un paquete de npm desarrollado por el equipo de AngularJS.

Cuando lo tenga probado compartiré como configurarlo en nuestros proyectos AngularJS y ejemplos.

tags: , , , , ,