Emmett is a tool named after Dr Emmett Brown from Back to the Future.
It's purpose is simple - given an index page and a bunch of API documents, it'll take them and generate a nice, usable website people can use to consume the documentation.
It doesn't automate the docs or the like - it just does the simplest thing possible.
Emmett is simply a pipeline for building documentation. It expects very little, namely:
- There is a specific api index page.
- There is a directory holding all API section information as markdown files
- Each page has a h1 with the section name
- Each page has one or more h2's with an api endpoint described inside a single one.
From this, it will generate compiled HTML from a template (the default is built on bootstrap) with:
- Markdown processed much like on GitHub.
- A nav bar with your api name + drop downs of section titles.
- An index of endpoints in each section before any of the endpoints are described.
- An api index on the home page.
It'll automatically use Pygments for code highlighting, so for http examples we encourage the syntax like:
```http
GET /1/your/endpoint HTTP/1.1
Authorization: Bearer TOKEN
``
```http
HTTP/1.1 200 OK
Content-Type: text/plain
Alrighty then!
```
AKA, Calls described in the form of a simplified request lifecycle.
Add this line to your application's Gemfile:
gem 'emmett'
And then execute:
$ bundle
Or install it yourself as:
$ gem install emmett
Emmett is primarily intended to be used as a rake task.
Want to generate the documentation directly in your application?
To configure it, the following options are available - simply put them in
config/application.rb
and change them as fit:
config.emmett.name = "Your App"
config.emmett.index_page = "doc/api.md" # Relative to doc/
config.emmett.section_dir = "doc/api" # Relative to doc/
config.emmett.output_dir = "doc/generated-api"
config.emmett.template = :default
It will use sane defaults (all being the same as above except the name, which is
the rails root dir titleize. I do suggest changing this). In Rails, it will
be available via rake doc:api
.
Likewise, you can use emmett inside any application thanks to the Rake Task.
In your Rakefile, simply add:
require 'emmett/rake_task'
Emmett::RakeTask.new :docs do |t|
t.name = "Your App"
t.index_page = "api.md"
t.section_dir = "api"
t.output_dir = "output"
t.template = :default
end
Like the rails version, this will use the values above as output, with the name being based on the current directory name.
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Added some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request
Emmett is released under the MIT License (see the license file) and is copyright Filter Squad, 2012.