Reacco is a dead simple documentation generator that lets you document your project using Markdown.
$ gem install reacco
Install Reacco first. It is a Ruby gem.
$ reacco
To generate documentation, type reacco
. This takes your README.md
file and
prettifies it.
$ reacco --literate
To make literate-style blocks (that is, code on the right, explanation on the
left), use reacco --literate
.
$ reacco --literate --api lib/
To extract documentation from your code files, add --api <path here>
. This
extracts comment blocks from files in that path.
As Reacco only parses out Markdown from your comments, almost all languages that
comments in #
and //
are supported. It does not care about code at all, just
comments.
# ## Reacco [class]
# The main class.
#
# Class documentation goes here in Markdown form.
#
class Reacco
...
end
You will need to add Markdown comment blocks to your code. The first line needs
to be a Markdown heading in the form of ### <heading name>
.
Classes are often made to be H2's.
# ## Reacco [class]
# The main class.
#
class Reacco
# ### version [class method]
# Returns a string of the library's version.
#
# #### Example
# This example returns the version.
#
# Reacco.version
# #=> "0.0.1"
#
def self.version
...
end
end
Class methods are often made as H3's. Sub-sections are often always H4's.
# README.md:
Please see http://you.github.com/project. [](#api_reference)
To specify where the docs will be in the README, put a line with the text
[](#api_reference)
. This will tell Reacco where to "inject" your API
documentation.
This is the main module.
Reacco.root
#=> '/usr/local/ruby/gems/reacco-0.0.1'
Returns the root path of the Reacco gem. You may pass additional parameters.
Reacco.markdown
#=> #<Redcarpet::Markdown ...>
Returns the Redcarpet Markdown processor. This is an instance of
Redcarpet
with all the right options plugged in.
A readme file.
readme = Reacco::Readme.new
readme = Reacco::Readme.new [OPTIONS HASH]
This is often instanciated by the reacco
executable, but you can instantiate
it yourself like so. It's assumed the the base dir will be the current working
directory.
readme.file #=> "README.md"
The path to the README file. Returns nil
if not available.
readme.switches #=> [ 'literate' ]
The switches, like literate and toc. Returns an array of strings.
readme = Readme.new :file => 'non-existent-file.txt'
readme.exists?
#=> false (maybe)
Returns true if the file (given in the constructor) exists.
readme.raw
#=> "# My project\n#### This is my project\n\n..."
Returns raw Markdown markup.
readme.title
#=> "My project"
Returns a string of the title of the document. Often, this is the first H1, but if that's not available, then it is inferred from the current directory's name.
readme.raw_html
#=> "<h1>My project</h1>..."
Returns a string of the raw HTML data built from the markdown source. This does not have the transformations applied to it yet.
Adds an API block. Takes an html
argument.
readme.raw_html
#=> "<h1>My project</h1>..."
Returns body's inner HTML with transformatinos.
readme.github
#=> "https://github.com/rstacruz/reacco"
Returns the GitHub URL, or nil if not applicable.
readme.locals
#=> { :title => 'My project', ... }
Returns a hash with the local variables to be used for the ERB template.
markdown.render(md)
Returns the Markdown processor.
"Install instructions" => "install_instructions"
Turns text into a slug.
Here be dragons! this is mostly made for my own projects, so I may change things quite often (though I'd try to be mostly API-compatible with older versions).
© 2011, Rico Sta. Cruz. Released under the MIT License.
Reacco is authored and maintained by Rico Sta. Cruz with help from it's contributors. It is sponsored by my startup, Sinefunc, Inc.