Tag Archives: Markdown

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