Rdoc. Documentar programas Ruby.

¿Que es Rdoc?

RDoc es el generador de documentación de Ruby por defecto a partir de la version 1.8.2, diseñado por Dave Thomas. Analiza el código fuente Ruby generando una estructura de las colecciones de paquetes para los objetos y métodos. Es capaz de realizar un análisis sintáctico recursivo de un directorio y encontrar todos los archivos .rb, .rbw y .c en busca de comentarios encima de la definición de cada función y al inicio del fichero. El formato de salida es HTML y crea el archivo en el subdirectorio doc.

RDOC es útil incluso si el código fuente de destino no contiene comentarios explícitos. RDOC aún analizará las clases, módulos y métodos, y la lista de ellos en los archivos generados de la API.

RDOC también proporciona el motor para la creación de archivos Ruby ri. ri es la versión de Ruby de páginas de manual, que sirve de información de la API de la línea de comandos.

RDOC y ri actualmente son mantenidos por Eric Hodel y Ryan Davis.

Instalación con RVM

$ gem install rdoc

Ejecución

Para ejecutar RDoc hay que llamarlo con el siguiente comando rdoc y se pueden utilizar algunos flags:

• --main [PATH a un fichero], hará que el fichero apuntado sea el que aparezca como inicio en la documentación generada.
• --all, incluye también métodos privados en la documentación (por defecto solo incluye los públicos).
• --op [PATH a un directorio], utiliza este directorio para guardar la documentación en lugar de "doc".
• --o [PATH a un directorio], directorio origen, sino toma desde donde se le llama.
• --inline-source, incluye el código fuente de cada método en la documentación.

Ejecución con RVM

$ rdoc + tabulador
rdoc                               rdoc-ruby-1.8.7-p302@global
rdoc-data                          rdoc-ruby-1.8.7-p302@gemset2l
rdoc-ruby-1.8.7-p302               rdoc-ruby-1.9.2-p0
rdoc-ruby-1.8.7-p302@gemset1       rdoc-ruby-1.9.2-p0@global

Documentar nuestra aplicación Rails

rake doc:app

Generating HTML...

Files: 28
Classes: 17
Modules: 12
Methods: 108
Elapsed: 1.914s


Reglas basicas de marcado

• = cabecera de nivel 1.
• == cabecera de nivel 2.
• === Cabecera de nivel 3
• etiqueta:: para hacer referencia a una etiqueta o label
• * o - crea un elemento de una lista.
• # crea un elemento de una lista numerada.
• Con las palabras se puede hacer: *negrita*, _itálica_ y +codigo+.
• Tambien podemos usar <b></b> , <em></em> , <tt></tt>
  

Otras marcas:

• :title: MyClase
• :include: Incluye el contenido de un archivo especifico en la documentación. La sangría se ajustara para tener consistencia.
• :main: Establecer la página inicial que aparecen en la salida.
• :nodoc: No documentamos algo
• :nodoc: all No se documentara algo, ni lo que contenga. (recursivo)
  

Ejemplo práctico

# = 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 --op ~/destino_ejemplo_rdoc/

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


Fuentes
wikipedia spejman maestrosdelweb rdoc rdoc v3 elcodigok handy rails

Otro ejemplo
http://socios.aditel.org/~andreu/ruby/rdoc_example/
http://socios.aditel.org/~andreu/ruby/apuntes.pdf

Chuleta Git

• Crear una rama foo

$ git branch foo


• Movernos a la rama foo

$ git checkout foo


• Uniendo ramas en git (merge) [draxus]

si tenemos dos ramas de desarrollo de un mismo proyecto en un repositorio git y llegado a un punto queremos juntarlas, podemos hacer lo siguiente:

$ git checkout foo
$ git pull . bar

Siendo bar el nombre de la rama que queremos unir con la rama foo.

Ahora es posible que existan conflictos entre ficheros que hayamos modificado en ambas ramas, para corregirlos, usaremos:

$ git mergetool -t herramienta_diff

En Linux podemos usar meld como herramienta, instalación:

$ sudo aptitude install meld

• Pausar desarrollo (git stash) [malev's blog]
  
git stash
git pull
# working on changes
git add .
git commit -m “a message”
git stash pop
# continue as nothing has happened

  

Fuentes:
ProGit draxus malev's blog

Mostrar la rama de Git en el Prompt con Ruby

Con Ruby instalado añadimos al fichero ~/.bashrc el código de abajo:

export PS1="\[\033[38m\]\u@\h\[\033[01;34m\] \w \[\033[31m\]\`ruby -e \"print (%x{git branch 2> /dev/null}.grep(/^\*/).first || '').gsub(/^\* (.+)$/, '(\1) ')\"\`\[\033[37m\]$\[\033[00m\] "

Es todo una sola linea.

Edito:

El método grep no está definido en ruby 1.9.2, una alternativa sin usar ruby:

export PS1="\[\033[38m\]\u@\h\[\033[01;34m\] \w \[\033[31m\]\`git branch 2> /dev/null | grep -e ^* | sed -E s/^\\\\\\\\\*\ \(.+\)$/\(\\\\\\\\\1\)\ /\`\[\033[37m\]$\[\033[00m\] "


Enlace: asemanfar

Como importar tus helpers a script/console

>> foo = ActionView::Base.new
=> #<ActionView::Base:0x2aaab0ac2af8 @assigns_added=nil, @assigns={},
@helpers=#<ActionView::Base::ProxyModule:0x2aaab0ac2a58>, @controller=nil, @view_paths=[]>

>> foo.extend YourHelperModule
=> #<ActionView::Base:0x2aaab0ac2af8 @assigns_added=nil, @assigns={},
@helpers=#<ActionView::Base::ProxyModule:0x2aaab0ac2a58>, @controller=nil, @view_paths=[]>

>> foo.your_helper_method(args)
=> "<html>created by your helper</html>"

Fuente Atlantageek