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:
And then execute:
Or install it yourself as:
$ gem install emmett
Emmett is primarily intended to be used as a rake task.
Emmett + Rails
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
Emmett on it's own.
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.