Tag Archives: NgDocs

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: , , , , ,