La documentación de las gemas de ruby se genera a partir del código fuente mediante rdoc. Después de eso puedes optar por ver individualmente cada una o usar gem server.
Para poder mejorar todo esto podemos usar par de útiles herramientas: (1) la plantilla para rdoc, hanna; y (2)bdoc como alternativa a gem server para visualizar la documentación.
Hanna es una plantilla para rdoc que mejora notablemente el formato por defecto. Podemos ver la diferencia fácilmente, por ejemplo, en la documentación de rspec con el formato típico vs la documentación hecha con hanna. La instalación es simple:
$ sudo gem sources -a http://gems.github.com $ sudo gem install mislav-hanna |
Para que a partir de ahora se generar la documentación con esta plantilla, puede añadir a tu .gemrc la siguiente línea:
rdoc: --inline-source --line-numbers --template=hanna
Y para convertir la documentación de todas tus gemas instaladas, puedes hacer algo como esto:
$ sudo gem list | awk '{print $1}' | xargs sudo hanna --gems |
Por otro lado, gracias a bdoc podremos navegar fácilmente entre todas las documentaciones.
$ sudo gem install manalang-bdoc $ bdoc |
Ejecutando bdoc se nos abrirá en nuestro navegador por defecto listo para poder leer la documentación y poder movernos fácilmente entre las diferentes gemas (y versiones). Muy útil.