Documentando tu aplicación Rails
Hoy leí algo muy interesante para documentar mockups o diseños de interfase usando algo llamado Documentos de Descripción del Diseño (o algo así).
Me pareció muy interesante, y se me ocurrió implementarlo para documentar código fuente de Rails.
Creo que este tipo de documentación puede ser muy útil cuando estas desarrollando, o incluso para mostrar un prototipo al cliente, porque puede ver muy fácilmente que esperar que haga la aplicación en cada paso.
Escribí un crudo plugin para hacer esto, y su objetivo es documentar las acciones de los controladores. Espero esta imagen te lo explique mejor:
Ese panel aparece en todas las acciones que tienen documentación definida. En el ejemplo anterior podría ser así:
- class SesionesController
# DD: Validar credenciales de usuario.
def iniciar_sesion
# DD: Inicio de sesión:
# # El usuario escribe su login y clave de acceso
# # El usuario da clic en el botón "Iniciar sesión"
# # El sistema válida la información. Si es correcta el usuario es llevado a su cuenta.
hacer_algo_util
# DD: Errores:
# p. El usuario escribe un login incorrecto
# # Se muestra un error en el campo de login
# DD: El usuario escribe una clave incorrecta
# # Se muestra un error en el campo de clave
mas_codigo_rails
etc
end
end
El panel puedes arrastrarlo por la pantalla, “minimizarlo” (doble clic en el título), o cerrarlo por completo (X).
Escribí el plugin muy rápido, así que esta horrendo. Quiero escuchar opiniones antes de “embellecerlo”. Notarán quienes tengan experiencia escribiendo “parsers” que yo no la tengo, así que una ayudadita no caería mal :-)
La instalación no es tan rápida como la de otros plugins, pero de momento creo que es suficiente. Primero baja este archivo y descomprimelo en la carpeta vendor/plugins. Dentro de vendor/plugins/rd3/lib encontrarás una hoja de estilo. Copiala a public/stylesheets.
Luego en el layout de cada controlador (o en el de la aplicación), agrega lo siguiente en la sección *“head”*:
- <%= stylesheet_link_tag 'rd3' %>
- <%= javascript_include_tag :defaults %>
Ahora escribe la documentación que quieras para tus controladores con la siguiente guía:
- class SesionesController
# DD: Descripción de la acción.
def iniciar_sesion
# DD: Documentación sobre la acción
# Este comentario es parte del anterior.
codigo
# DD: Otra sección de documentación
# p. Acepta formato de RedCloth
# # Esta es una lista
# # Otro elemento
mas_codigo
# Este es un comentario normal que no será incluido
# en la documentación generada.
end
end
Bien, ya que tienes tu controlador documentado, en la consola ejecutas una tarea de rake:
- rake rd3:update
Eso creará unas vistas en doc/rd3, que serán las que aparecen en el panel.
Puedes personalizar este panel ya sea con el archivo CSS incluido o editando la plantilla rd3/lib/panel.erb.
Ah, casi lo olvidaba, este plugin solo se carga cuando estas en ambiente de desarrollo. En producción por supuesto ya no.
Agradeceré cualquier crítica que me puedan ofrecer :-)