RDoc es una herramienta diseñada por David Thomas, un reconocido programador apasionado por Ruby y a su vez, escritor de los más famosos libros sobre Ruby (Programming Ruby, Agile Web Development with Rails, etc)

RDoc tiene la particularidad de analizar el código fuente de las aplicaciones y automáticamente generar una colección de páginas organizadas identificando los objetos, clases y métodos que componen la estructura de código fuente de las aplicaciones en Ruby.

Instalación de RDoc

Tal y como vimos en el artículo anterior relacionado con RubyGems, RDoc también forma parte de las gemas que encontramos en Ruby, y para instalarla es sumamente simple, por ejemplo para buscar en los servidores remotos

$ gem query --remote --name-matches rdoc

*** REMOTE GEMS ***
darkfish-rdoc (1.1.5)
murdoch (1.0.1)
quality_rdoc (0.0.1)
rdoc (2.4.3)
rdoc-f95 (0.0.2)
rdoc_chm (2.4.2)
rdoc_html_templates (2.3.0)
rdp-rdoc (2.4.6)

Con lo cuál obtenemos una lista de aquellas gemas relacionadas a rdoc, solo nos quedará seleccionar la gema rdoc cuya versión es 2.4.3 e instalarla de la siguiente manera

$ gem install --remote rdoc

Ahora podemos corroborar que realmente se instalo la gema rdoc

$ gem list --local

*** LOCAL GEMS ***
rdoc (2.4.3)

Ahora estamos en condiciones de poder utilizar este maravilloso generador de documentación.

Formatos de Documentación

Antes de comenzar a realizar las prácticas conozcamos alguna de las marcas más utilizadas:

  • = Cabecera de Primer nivel
  • == Cabecera de Segundo nivel
  • === Cabecera de Tercer nivel
  • etiqueta:: para hacer referencia a una etiqueta o label
  • ‘*’ o ‘-‘ Para crear elementos de una lista
  • # Para crear elementos en una lista enumerada
  • _italic_ para aquellas palabras en cursiva
  • *negrita* para aquellas palabras que deseamos resaltar
  • +codigo+ para resaltar fragmentos de código

Ejemplo práctico

Llego el momento de conocer el potencial de rdoc en acción, lo primero que podemos hacer es crear un script simple en su editor de texto favorito bajo el nombre de ejemplo_rdoc.rb y con un contenido similar a el que figura abajo, en donde hagamos uso de alguno de los Markups para apreciar bien el funcionamiento.

# = ejemplo_rdoc.rb
#
# Autor::   Daniel Martin Maldonado
# Web::     http://www.elcodigok.com.ar
#
# == Ejemplo
#
# Con este pequeño ejemplo pretendemos:
# - Dar a conocer la herramient *rdoc*
# - Mostrar como se utilizan los Markpu
# - Mostrar la sencillez de su implementación en pequeños y grandes proyectos
#
# === Clase Persona
#
# Definición de la clase _Persona_ compuesta por
# * metodo initialize
# * metodo saludar
#

class Persona
  def initialize(nombre)
    @nombre = nombre
  end
  def saludar
    puts "Hola, me llamo #{@nombre}"
  end
end

daniel = Persona.new("Daniel")
daniel.saludar

Para obtener su documentación podemos hacerlo de la siguiente manera:

$ rdoc --main -o documento ejemplo_rdoc.rb

Parsing sources with 2 thread(s)...
100% [ 1/ 1]  ejemplo_rdoc.rb
Generating Darkfish...
Files:   1
Classes: 1
Modules: 0
Methods: 2
Elapsed: 0.4s

Con el argumento -o nos creará un directorio llamado documento en donde almacenó todos los archivos html correspondientes a la documentación, si no lo especificamos por defecto lo creará en el directorio doc.

El argumento –main toma como página principal al único archivo que tenemos creado.

Una práctica que les recomiendo para probarlo en grandes y medianos proyecto es que se descarguen cualquiera de las gemas que podemos encontrar RubyForge.org por ejemplo descargar la última versión de rubygems (http://rubyforge.org/frs/download.php/60718/rubygems-1.3.5.tgz), descomprimir el archivo y por último dentro de la raíz principal ejecutar:

$ rdoc --all -o documentacion

Nuevamente si revisamos el directorio documentacion, vamos a encontrar todos los archivos html que componen a la documentación recientemente generada.

Conclusión

Hoy vimos una de las herramientas más interesantes de Ruby, RDoc su generador de documentación automática que con el simple uso de algunas etiquetas o Markup podemos llegar a tener una documentación con un formato profesional y de manera instantánea. Hay más información en Wikipedia, Spejmank, elcodigok y Wikibooks.