Brincando com RubyGems / RDoc

Com muitos sabem, o gerenciador de pacotes do Ruby é o RubyGems. Por padrão, quando o Ruby é instalado no Windows (geralmente com o pacote One Click Installer) o rubygems já está disponível. Para ter certeza disso, basta ir ao prompt e digitar "gem -v". Esse comando deve devolver a versão atual do rubygems instalado.

De posse do rubygems é possível instalar diversas gems, que de forma geral podemos chamar de plugins. Tais gems dão possibilidade de incrementar o seu ruby com novas bibliotecas que ajudarão em determinadas circunstâncias.

Imagine que você precisa criar uma rotina em ruby que manipule páginas HTML, pegando trechos dessas páginas para montar um relatório por exemplo. Para fazer isso existem diversas formas, uma delas seria você criar do zero várias rotinas de acesso e manipulação das páginas HTML, ou se preferir instalar a gem Hpricot, que adiciona ao ruby ótimas funcionalidades de manipulação de páginas HTML.

Muito bem, resolvi escrever esse pequeno tutorial para mostrar como é possível acessar a documentação das gems instalas de uma forma off-line, já que na maioria das vezes verificamos como utilizá-la procurando na internet.

O sistema de gerenciamento de pacotes ruby dá a possibilidade de acessar de forma off-line toda e qualquer documentação que a gem possui quando instalada.

O procedimento é bem simples. Vamos seguir mostrando que um pouco de curiosidade possibilita descobrir muitas coisas.

Digitando "gem --help" no prompt temos a seguinte saída:

RubyGems is a sophisticated package manager for Ruby.  This is a
basic help message containing pointers to more information.

Usage:
gem -h/--help
gem -v/--version
gem command [arguments...] [options...]

Examples:
gem install rake
gem list --local
gem build package.gemspec
gem help install

Further help:
gem help commands            list all 'gem' commands
gem help examples            show some examples of usage
gem help platforms           show information about platforms
gem help            show help on COMMAND
                              (e.g. 'gem help install')
gem server                   present a web page at
                            http://localhost:8808/
                            with info about installed gems
Further information:
http://rubygems.rubyforge.org

Basta ler a saída e verificar que dentre as opções apresentadas existe uma "gem server" que por sua descrição "apresentará uma página web em http://localhost:8808 com informações sobre as gems instaladas". Pois bem, vamos fazer isso, digite "gem server" no prompt e verifique no browser, acessando http://localhost:8808 que é possível ter informações sobre todas as gems instaladas.


Após analisar as informações das gems, é possível acessar seus respectivos RDocs, mas, também é possível notar que algumas delas não possuem o RDoc disponível, então, voltando ao prompt verificamos que uma das opções disponíveis quando digitado "gem --help" é o comando "gem help commands" que mostrará a seguinte saída:

C:\>gem help commands
GEM commands are:

build             Build a gem from a gemspec
cert              Manage RubyGems certificates and signing settings
check             Check installed gems
cleanup           Clean up old versions of installed gems in the local
                  repository
contents          Display the contents of the installed gems
dependency        Show the dependencies of an installed gem
environment       Display information about the RubyGems environment
fetch             Download a gem and place it in the current directory
generate_index    Generates the index files for a gem server directory
help              Provide help on the 'gem' command
install           Install a gem into the local repository
list              Display gems whose name starts with STRING
lock              Generate a lockdown list of gems
mirror            Mirror a gem repository
outdated          Display all gems that need updates
pristine          Restores installed gems to pristine condition from files
                  located in the gem cache
query             Query gem information in local or remote repositories
rdoc              Generates RDoc for pre-installed gems
search            Display all gems whose name contains STRING
server            Documentation and gem repository HTTP server
sources           Manage the sources and cache file RubyGems uses to search
                  for gems
specification     Display gem specification (in yaml)
stale             List gems along with access times
uninstall         Uninstall gems from the local repository
unpack            Unpack an installed gem to the current directory
update            Update the named gems (or all installed gems) in the local
                  repository
which             Find the location of a library file you can require

For help on a particular command, use 'gem help COMMAND'.

Commands may be abbreviated, so long as they are unambiguous.
e.g. 'gem i rake' is short for 'gem install rake'.

Verifique que existe um comando chamado "rdoc" e que sua descrição indica que ele serve para gerar o RDoc de gems previamente instaladas, e é isso que vamos fazer. Aqui no meu caso eu tinha a gem Hpricot instalada, mas não tinha o RDoc disponível para consulta, então rodei o comando "gem rdoc hpricot" e visualizei no prompt o seguinte:

C:\>gem rdoc hpricot
Installing ri documentation for hpricot-0.4-x86-mswin32...
Installing RDoc documentation for hpricot-0.4-x86-mswin32...

Voilá! Acessando novamente o "gem server" pude acessar sem problemas a documentação RDoc da gem.

É isso, acredito que conhecendo bem o RubyGems podemos tirar muito proveito da ferramenta.

[]'s