Tag Archives: Javascript

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

Egghead.io, aprendamos AngularJS desde 0

Web

angularjsBueno, hace unos días que abrí el blog y ya toca empezar a darle fuelle a esto.

Este post no sé si puede ser muy de mucha ayuda, pero como creo que de lo que se trata un blog es intentar compartir lo que cada uno encuentra positivo en la red. pues aquí os dejo esto.

Últimamente, en charlas con compañeros del gremio, cuando hablamos de proyectos, salta el tema AngularJS, en base a un gran proyecto que desarrollamos en mi trabajo (focusonemotions.com), tuvimos que decantarnos por un framework JS y lo hicimos por AngularJS, por lo que tuvimos que aprender desde 0 como funcionaba este y dedicamos 1 semana de prueba y error para ver, de que mejor forma, desarrollábamos las funcionalidades para cumplir los requisitos planteados.

Y bueno, siempre que salta este tema, recomiendo encarecidamente Egghead.io, que mas que una web de tutoriales, para mi fue (y es) una biblia. Cuando, con mis compañeros empezamos ha hacer los tutoriales de este site, tan solo tenía unos 30 videos, practicamente era una web mas que te daba videos gratuitos para aprender AngularJS, eso si, cada video de media unos 3 a 5 minutos, pero con las palabras justas, explicaciones concisas y ejemplos muy claros.

Hoy día, sigue igual, con la misma idea, pero ahora puedes encontrar todo lo que puedas complementar con un proyecto en AngularJS, con mas de 100 vídeos, que algunos requieren suscripción de pago, pero creo, que haciendo los tutoriales gratuitos, probando y dándole un par de vueltas, aprendes mucho, aunque teniendo la confianza de estos, veo una buena inversión gastar un poco para acceder a los vídeos PRO y ver que mas nos puede contar.

tags: ,