<commit_before>= <NAME> — a better RDoc template, now for RDoc 4.

Based on the original Hanna by Mislav.

Hanna is an RDoc generator that scales. It's implemented in Haml, making the
sources clean and readable. It's built with simplicity, beauty and ease of
browsing in mind.

Hanna gem is available from http://rubygems.org:

    gem install hanna-nouveau

The template was created by {Mislav}[http://mislav.uniqpath.com/] and since then
has seen contributions from:

1. {<NAME>}[http://github.com/DesigningPatterns], who participated from
   the early start and made tons of fixes and enhancements to the template;
2. {<NAME>}[http://blog.phusion.nl/] with the search filter for methods.
3. {<NAME>}[http://github.com/erikh] a serious refactoring and up to
   date with RDoc 2.5.x and 3.x, now named 'hanna-nouveau'.
4. {<NAME>}[http://github.com/raggi] minor cleanups for Erik.
5. {<NAME>}[http://github.com/jeremyevans] RDoc 4 support, maintenance
   since 2014.

== Usage

    rdoc -o doc -f hanna lib/*.rb

An alternative is to set the `RDOCOPT` environment variable:

    RDOCOPT="-f hanna"

This will make RDoc always use hanna-nouveau unless it is explicitly overridden.

== Integrating with RubyGems

Another neat trick is to put the following line in your .gemrc, this will make
RubyGems use Hanna for all rdoc generation:

    rdoc: -f hanna

This will make RubyGems use Hanna when generating documentation for installed
gems. Remember, if you wish to have all your gems be formatted in hanna:

    gem rdoc --all --overwrite

The first time. To easily browse your newly created documentation, use:

    gem server

== Rake task

For repeated generation of API docs, it's better to set up a Rake task. Simply
add the hanna format argument to your RDoc::Task options:

    gem 'rdoc'
    require 'rdoc/task'
    RDoc::Task.new do |rdoc|
      # this only works with RDoc 3.1 or greater
      rdoc.generator = 'hanna'
      # this is what you use pre RDoc 3.1:
      rdoc.options.push '-f', 'hanna'
    end

Tip: you can do this in the Rakefile of your Rails project before running
`rake doc:rails`.

Here is an example of a task for the {rdbi
library}[http://github.com/rdbi/rdbi/tree/master/Rakefile]:

    gem 'rdoc'
    require 'rdoc/task'
    RDoc::Task.new do |rdoc|
      version = File.exist?('VERSION') ? File.read('VERSION') : ""

      rdoc.generator = 'hanna'
      rdoc.main = 'README.rdoc'
      rdoc.rdoc_dir = 'rdoc'
      rdoc.title = "RDBI #{version} Documentation"
      rdoc.rdoc_files.include('README*')
      rdoc.rdoc_files.include('lib/**/*.rb')
    end

== Modification to RDoc

Hanna makes a small modification to RDoc to generate more
friendly documentation.  It changes label lists to use a table
instead of a description list, since it is very difficult to
get visually appealing styling for description lists without
cutting corners (like using fixed widths).
<commit_msg>Minor tweaks to the README<commit_after>= Hanna-nouveau

Based on the original Hanna by Mislav.

Hanna-nouveau is an RDoc generator that scales. It's implemented in Haml,
making the sources clean and readable. It's built with simplicity, beauty
and ease of browsing in mind.

Hanna-nouveau is distributed as a ruby gem:

    gem install hanna-nouveau

The template was created by {Mislav}[http://mislav.uniqpath.com/] and since then
has seen contributions from:

1. {<NAME>}[http://github.com/DesigningPatterns], who participated from
   the early start and made tons of fixes and enhancements to the template;
2. {<NAME>}[http://blog.phusion.nl/] with the search filter for methods.
3. {<NAME>}[http://github.com/erikh] a serious refactoring and up to
   date with RDoc 2.5.x and 3.x, now named 'hanna-nouveau'.
4. {<NAME>}[http://github.com/raggi] minor cleanups for Erik.
5. {<NAME>}[http://github.com/jeremyevans] RDoc 4 support, maintenance
   since 2014.

== Usage

    rdoc -o doc -f hanna lib

An alternative is to set the `RDOCOPT` environment variable:

    RDOCOPT="-f hanna"

This will make RDoc always use hanna-nouveau unless it is explicitly overridden.

== Integrating with RubyGems

Another neat trick is to put the following line in your .gemrc, this will make
RubyGems use Hanna for all rdoc generation:

    rdoc: -f hanna

This will make RubyGems use Hanna when generating documentation for installed
gems. Remember, if you wish to have all your gems be formatted in hanna:

    gem rdoc --all --overwrite

The first time. To easily browse your newly created documentation, use:

    gem server

== Rake task

For repeated generation of API docs, it's better to set up a Rake task. Simply
add the hanna format argument to your RDoc::Task options:

    gem 'rdoc'
    require 'rdoc/task'
    RDoc::Task.new do |rdoc|
      rdoc.generator = 'hanna'
    end

Tip: you can do this in the Rakefile of your Rails project before running
`rake doc:rails`.

Here is an example of a task for the {rdbi
library}[http://github.com/rdbi/rdbi/tree/master/Rakefile]:

    gem 'rdoc'
    require 'rdoc/task'
    RDoc::Task.new do |rdoc|
      version = File.exist?('VERSION') ? File.read('VERSION') : ""

      rdoc.generator = 'hanna'
      rdoc.main = 'README.rdoc'
      rdoc.rdoc_dir = 'rdoc'
      rdoc.title = "RDBI #{version} Documentation"
      rdoc.rdoc_files.include('README*')
      rdoc.rdoc_files.include('lib/**/*.rb')
    end

== Modification to RDoc

Hanna makes a small modification to RDoc to generate more
friendly documentation.  It changes label lists to use a table
instead of a description list, since it is very difficult to
get visually appealing styling for description lists without
cutting corners (like using fixed widths).

{'fraction_non_alphanumeric': 0.09062059238363893, 'fraction_numerical': 0.005465444287729196, 'mean_word_length': 3.531150159744409, 'pattern_counts': {'":': 0, '<': 14, '<?xml version=': 0, '>': 14, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3978928', 'n_tokens_mistral': 1840, 'n_tokens_neox': 1736, 'n_words': 733}