Fork me on GitHub

Reacco

Readme documentation prettifier

Reacco is a dead simple documentation generator that lets you document your project using Markdown.

Usage

Installation

$ gem install reacco

Install Reacco first. It is a Ruby gem.


Generation

$ reacco

To generate documentation, type reacco. This takes your README.md file and prettifies it.


Literate style blocks

$ reacco --literate

To make literate-style blocks (that is, code on the right, explanation on the left), use reacco --literate.


Documenting API

$ 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.


Documenting classes

# ## 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.


Documenting class methods

# ## 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.


Adding the placeholder

# 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.


API reference

Reacco module

This is the main module.

root class method

Reacco.root
#=> '/usr/local/ruby/gems/reacco-0.0.1'

Returns the root path of the Reacco gem. You may pass additional parameters.


markdown class method

Reacco.markdown
#=> #<Redcarpet::Markdown ...>

Returns the Redcarpet Markdown processor. This is an instance of Redcarpet with all the right options plugged in.


Reacco::Readme class

A readme file.

Instanciating

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.


Options

Avaiable options are (all are optional):

  • file - String (the filename of the README file)
  • literate - Boolean
  • toc - Boolean

file method

readme.file      #=> "README.md"

The path to the README file. Returns nil if not available.


switches method

readme.switches  #=> [ 'literate' ]

The switches, like literate and toc. Returns an array of strings.


exists? method

readme = Readme.new :file => 'non-existent-file.txt'
readme.exists?
#=> false (maybe)

Returns true if the file (given in the constructor) exists.


raw method

readme.raw
#=> "# My project\n#### This is my project\n\n..."

Returns raw Markdown markup.


title method

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.


raw_html method

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.


inject_api_block method

Adds an API block. Takes an html argument.

doc([options]) method

readme.doc
#=> #<Nokogiri::HTML ...>

Returns HTML as a Nokogiri document with all the transformations applied.


html method

readme.raw_html
#=> "<h1>My project</h1>..."

Returns body's inner HTML with transformatinos.


github method

readme.github
#=> "https://github.com/rstacruz/reacco"

Returns the GitHub URL, or nil if not applicable.


locals method

readme.locals
#=> { :title => 'My project', ... }

Returns a hash with the local variables to be used for the ERB template.


markdown private method

markdown.render(md)

Returns the Markdown processor.


slugify private method

"Install instructions" => "install_instructions"

Turns text into a slug.


Warning

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).

Acknowledgements

© 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.