How to create API documentation for projects in GitHub?

Question

I have several ruby and rails projects hosted in GitHub.

I wonder how I could create API documentation for these automatically?

Examples:

http://rake.rubyforge.org/

http://rspec.rubyforge.org/rspec/1.3.0/

Are there tutorials for creating this API docs in Ruby?

Answer 1

http://rdoc.info ca help you creating documentation directly from your github repository, go to http://rdoc.info/projects/new to add your project.

Answer 2

Both examples are generated using RDoc. The first one is the standard RDoc template, the second one is generated with Hanna.

You can easily generate the documentation using the RDoc command line tool or by creating a Rake task. For instance, this documentation is generated with the following task

begin
  require "hanna/rdoctask"
rescue LoadError
  require "rake/rdoctask"
end

# Generate documentation
Rake::RDocTask.new do |rd|
  rd.main = "README.rdoc"
  rd.rdoc_files.include("*.rdoc", "lib/**/*.rb")
  rd.rdoc_dir = "rdoc"
end

See the Rakefile for more details.

Answer 3

Github provides service hooks on a per-repository basis (that is, you can enable it for this or that repo, but not these other two over here). One of the hooks is tied into rdoc.info, which uses Yard to produce spiffy documentation. (Yard itself is similar to rdoc. If you know rdoc, you won't have any trouble picking up Yard.) Example: Yard's own docs.

In your repo, go to Admin -> Service Hooks and poke around. (See the note on this page for information about how to customize what files are scanned for documentation within a repository.)