QVINTVS · SCRIBET

hanna-nouveau - Vernünftiges und aktuelles RDoc-Template

Das RDoc-Template hanna ist bekanntlicherweise ja nicht kompatibel mit halbwegs aktuellen RDoc-Versionen (>= 2.4). Seit kurzem gibt es jedoch eine brauchbare Alternative: hanna-nouveau.

Möchte man hanna-nouveau installieren, so sollte man sich zuerst vom alten hanna-Gem trennen:

# gem uninstall hanna

Anschließend kann man voll Genuss RDoc auf die aktuelle Version aktualisieren und dann hanna-nouveau installieren:

# gem update rdoc
# gem install hanna-nouveau

Damit ist die Umstellung aber nicht getan, denn hanna-nouveau enthält die Executable hanna nicht mehr; es ist jetzt ein reines RDoc-Template. Für die von uns, die (wie ich) verlernt haben, wie man gewöhnliche RDoc-Templates benutzt:

$ rdoc -f hanna FILES

Auch bei der Verwendung hannas als Raketask hat sich ein bisschen was verändert. Anstatt wie bisher

require "hanna/rdoctask"

zu verwenden, bindet man den gewöhnlichen RDoc-Task ein und konfiguriert ihn so, dass er hanna als Generator benutzt (die dafür erforderliche Option generator ist erst in neueren RDoc-Versionen verfügbar):

require "rake"
gem "rdoc" #Wichtig, damit nicht das 1.9-interne RDoc benutzt wird
require "rdoc/task"

Rake::RDocTask.new do |rd|
  rd.rdoc_files.include("lib/**/**.rb", "**/**.rdoc")
  rd.title = "My RDocs"
  rd.main = "README.rdoc"
  rd.generator = "hanna" #<----- Hier wird hanna als Generator festgelegt
  rd.rdoc_dir = "doc"
 end

Möchte man hanna immer automatisch verwenden, kann man das in seiner RDOCOPT-Umgebungsvariable festlegen, z.B. so in der ~/.bashrc:

export RDOCOPT="-f hanna"

Fazit

Insgesamt gestaltet sich die Verwendung des neuen hanna-nouveau-Gems wirklich viel einfacher als das ständige Herumfrickeln am alten hanna, bis es denn dann lief (RDoc downgraden, bin/hanna patchen, damit sich hanna --gems nicht beschwert, Rakefiles auf den hanna-Task umstellen und LoadError rescuen, wenn nicht vorhanden…).

Dabei schaut das Ergebnis genauso aus wie beim Original-hanna, sodass ich nur jedem die Installation dieses wunderbaren Templates empfehlen kann.

Sources?

Ein Problem gibt es aber. Wie ich bereits in diesem Issue angemerkt habe, sind die Quelldateien scheinbar von Github verschwunden (sie sollten unter https://github.com/erikh/hanna-nouveau verfügbar sein). Wer sie dennoch sehen möchte, kann RubyGems benutzen:

$ gem fetch hanna-nouveau
$ gem unpack hanna-nouveau-0.2.2.gem

Update

Hanna-nouveau ist nun unter das Dach des offiziellen RDoc-Projekts gezogen: https://github.com/rdoc/hanna-nouveau. Dort gibt es auch den Quellcode.

Valete.