• This repository has been archived on 03/Mar/2020
  • Stars
    star
    234
  • Rank 171,599 (Top 4 %)
  • Language
    Ruby
  • License
    MIT License
  • Created over 16 years ago
  • Updated over 14 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

More than just a new RDoc template

Hanna — a better RDoc template

Hanna is an RDoc template 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. (See more in the wiki.)

Hanna gem is available from Gemcutter:

gem install hanna

The template was created by Mislav and since then has seen contributions from:

  1. Tony Strauss, who participated from the early start and made tons of fixes and enhancements to the template;
  2. Hongli Lai with the search filter for methods.

Usage

There is a command-line tool installed with the Hanna gem:

hanna -h

This is a wrapper over rdoc and it forwards all the parameters to it. Manual usage would require specifying Hanna as a template when invoking RDoc on the command-line:

rdoc -o doc --inline-source --format=html -T hanna lib/*.rb

Hanna requires the --inline-source (or -S) flag.

An alternative is to set the RDOCOPT environment variable:

RDOCOPT="-S -f html -T hanna"

This will make RDoc always use Hanna unless it is explicitly overridden.

Another neat trick is to put the following line in your .gemrc:

rdoc: --inline-source --line-numbers --format=html --template=hanna

This will make RubyGems use Hanna when generating documentation for installed gems.

Rake task

For repeated generation of API docs, it's better to set up a Rake task. If you already have an RDocTask set up in your Rakefile, the only thing you need to change is this:

# replace this:
require 'rake/rdoctask'
# with this:
require 'hanna/rdoctask'

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 will_paginate library:

# instead of 'rake/rdoctask':
require 'hanna/rdoctask'

desc 'Generate RDoc documentation for the will_paginate plugin.'
Rake::RDocTask.new(:rdoc) do |rdoc|
  rdoc.rdoc_files.include('README.rdoc', 'LICENSE', 'CHANGELOG').
    include('lib/**/*.rb').
    exclude('lib/will_paginate/named_scope*').
    exclude('lib/will_paginate/array.rb').
    exclude('lib/will_paginate/version.rb')
  
  rdoc.main = "README.rdoc" # page to start on
  rdoc.title = "will_paginate documentation"
  
  rdoc.rdoc_dir = 'doc' # rdoc output folder
  rdoc.options << '--webcvs=http://github.com/mislav/will_paginate/tree/master/'
end

Generating documentation for installed gems

You can generate documentation for installed gems, which might be more convenient than the gem rdoc command with the +RDOCOPT+ environment variable set as described. For instance, to generate docs for "actionpack" and "activerecord" type:

[sudo] hanna --gems actionpack activerecord

You can help

Don't like something? Think you can design better? (You probably can.)

I think of Hanna as the first RDoc template that's actually maintainable. First thing I have done is converted the original HTML template to Haml and Sass, cleaning up and removing the (ridiculous amount of) duplication. Also, the template fragments are now in separate files.

Ultimately, I'd like to lose the frameset. Currently that is far from possible because the whole RDoc HTML Generator is built for frames. Still, that is my goal.

This is git. Fork it, hack away, tell me about it!

More Repositories

1

hub

A command-line tool that makes git easier to use with GitHub.
Go
22,524
star
2

will_paginate

Pagination library for Rails and other Ruby applications
Ruby
5,706
star
3

git-deploy

git deployment made easy
Ruby
2,098
star
4

dotfiles

bash, zsh, git, tmux, personal toolbox
Shell
1,208
star
5

rfc

Pretty RFC indexes and reformats RFC documents for easier discovery and viewing.
JavaScript
935
star
6

poignant-guide

Why's Poignant Guide to Ruby
HTML
732
star
7

instagram

The first Instagram website and lightweight API HTTP client
Ruby
586
star
8

ssl-tools

Ruby tools to help with debugging certificates for SSL connections
Ruby
339
star
9

contacts

Ruby library for consuming Google, Yahoo!, Flickr and Windows Live contact APIs
Ruby
294
star
10

anyenv

rbenv-inspired version manager that can be configured to manage versions of ANYTHING
Go
273
star
11

vimfiles

vim configuration – Ruby, Rails, Markdown, SCSS, CoffeeScript
Vim Script
266
star
12

gh-branch

GitHub CLI extension for fuzzy finding, quickly switching between and deleting branches.
Shell
210
star
13

nibbler

A cute HTML scraper / data extraction tool in under 70 lines of code
Ruby
141
star
14

bump-homebrew-formula-action

Automatically bump Homebrew formula after a release
TypeScript
126
star
15

coral

Hacker's toolbelt for Ruby, gems, Bundler, git, and more
Shell
108
star
16

choices

Easy external settings for your app
Ruby
95
star
17

gorgeous

Convert between different data formats: JSON, XML, YAML, Ruby, email, URL-encoded
Ruby
94
star
18

movieapp

Mark movies you watched, liked, or plan to watch, and share with your friends.
Ruby
79
star
19

diveintohtml5

[STALE] Copy of Mark Pilgrim's book "Dive Into HTML5"
HTML
75
star
20

gh-cp

GitHub CLI extension to copy a file from a GitHub repository locally without cloning the repository.
Shell
72
star
21

issuesync

Downloads all issues for the current project to individual `issues/*.md` files
Ruby
67
star
22

twitter-login

Login through Twitter; DEPRECATED in favor of omniauth-twitter.
Ruby
63
star
23

rspec-rails-mocha

Ports functionality of mock_model and stub_model from rspec-rails for developers using Mocha.
Ruby
57
star
24

hub-api-utils

A collection of `hub api` examples
Shell
57
star
25

bluecloth

Markdown processor in Ruby; foked from official SVN repo to fix bugs
Ruby
49
star
26

faraday-stack

[deprecated] Über Faraday stack for consuming APIs (JSON, XML decoding & more)
Ruby
47
star
27

sinatra-boilerplate

Sinatra + Haml Sass Compass Bourbon CoffeeScript
JavaScript
41
star
28

gh-contrib

GitHub CLI extension to render your contribution graph in the terminal
Shell
39
star
29

explain-ruby

Explains Ruby syntax
Ruby
32
star
30

twin

Twitter's twin; a Rack middleware to expose a Twitter-like API from your app
Ruby
30
star
31

gh-repo-collab

GitHub CLI extension to manage repository collaborators
Shell
28
star
32

user-scripts

User scripts for Greasemonkey/Safari/Fluid; home of Endless Tweets
JavaScript
28
star
33

standardista

A nicotine patch for Rails users who want to stop pretending they're writing XHTML
Ruby
23
star
34

tapas-bar

Tiny webapp that I use for watching RubyTapas from my iPad across home network.
Ruby
20
star
35

polyamory

A tool that knows how to run your tests regardless of framework
Ruby
19
star
36

remark

HTML to Markdown converter
Ruby
18
star
37

gh-delete-repo

[Deprecated] GitHub CLI extension for deleting GitHub repositories
Shell
17
star
38

rbenv-user-gems

[DEPRECATED] rbenv plugin for $GEM_HOME and user gems install location
Shell
15
star
39

go-travis

Go-based CLI tool for Travis CI
Go
15
star
40

shrubbery

Nested lists unlike you've ever seen
JavaScript
14
star
41

thor-tasks

GitHub tasks for Thor
14
star
42

gh-license

GitHub CLI extension to add a license to the current project
Shell
14
star
43

blog

The blog
HTML
14
star
44

itunes

Access iTunes with MacRuby through Scripting Bridge
C
13
star
45

facebook

Facebook login; DEPRECATED in favor of omniauth-facebook.
Ruby
13
star
46

textmate-bundles

My fork of a repo that once was "textmate/bundles"
11
star
47

curly

Easier than Curl::Easy
Ruby
10
star
48

async-upload

Example app for asynchronous file upload via hidden iframe with Prototype and PHP
PHP
9
star
49

rbenv-charles-ssl

rbenv plugin to help installing Charles Proxy SSL certificate into all rubies
Shell
9
star
50

cstags

ctags generator for CoffeeScript files
CoffeeScript
9
star
51

puppet-personal

I'm learning Puppet. WIP
Ruby
8
star
52

mingo

Ruby
8
star
53

asbestos

Render JSON from your XML Builder templates
Ruby
7
star
54

twitter-followers

Mini app that processes new followers notifications from Twitter
JavaScript
7
star
55

svg2png

Convert SVGs to PNG using headless Chrome
JavaScript
6
star
56

gh-repo-topic

[Deprecated] GitHub CLI extension to list or add repository topics
Shell
6
star
57

never-forget

The stupid exception tracker. Saves to MongoDB.
Ruby
6
star
58

Lyndon.tmbundle

Execute JavaScript expressions with a single keystroke inside TextMate
6
star
59

gh-lint-workflow

A GitHub CLI extension to lint GitHub Actions workflow files [EXPERIMENTAL]
Shell
6
star
60

railsgirls-movieapp

Example application for Rails Girls workshop
Ruby
5
star
61

stylish.vim

vim plugin to cycle through available color schemes and fonts on your system
Ruby
4
star
62

goreleaser-test

Shell
3
star
63

gh-notifications

Ruby
3
star
64

go-utils

Go
3
star
65

tweets

Grailbird site that powers an individual Twitter Archive, edited for my needs
JavaScript
3
star
66

gh-label

1
star
67

pages-cname-instructions

How to host GitHub Pages site on your own domain
JavaScript
1
star