biomancer/apitome

Apitome: /iˈpitəmē/ An API documentation reader for RSpec API Documentation

Apitome

Apitome is a API documentation tool for Rails built on top of the great rspec DSL included in rspec_api_documentation (RAD). It's designed to display the documentation generated by RAD in either a single page (with scrollspy), or on individual pages, and uses Bootstrap3 for most of the basic styling and highlight.js for code highlighting.

You can provide a markdown file that will be displayed as the README page, and by taking advantage of its modular view structure you can override any number of views and partials to customize the output. You can also specify custom css and javascript if you want to do fancier things or change how it looks.

Installation

Add it to your Gemfile.

gem "apitome"

Optionally run the install generator to get the initializer and an initial readme file (doc/api.md).

rails generate apitome:install

Update your spec_helper.rb to adjust how RAD outputs its results -- Apitome reads these JSON files to generate the documentation.

RspecApiDocumentation.configure do |config|
  config.format = :json
end

Usage

You can view your documentation at the default api/docs route.

Configuration

After installation, your app will have an apitome initializer (app/config/initializers/apitome.rb). You will find the following parameters that can be used to customize apitome. Note: Restart rails after changing any of these parameters.

mount_at

This determines where the Apitome routes will be mounted. Changing this to "/api/documentation" for instance would allow you to browse to http://localhost:3000/api/documentation to see your api documentation. Set to nil and mount it yourself if you need to.

default: "/api/docs"

root

This defaults to Rails.root if left nil. If you're providing documentation for an engine using a dummy application it can be useful to set this to your engines root.. E.g. Application::Engine.root

default: nil

doc_path

This is where rspec_api_documentation outputs the JSON files. This is configurable within RAD, and so is configurable here.

default: "doc/api"

title

The title of the documentation -- If your project has a name, you'll want to put it here.

default: "Apitome Documentation"

layout

The main layout view for all documentation pages. By default this is pretty basic, but you may want to use your own application layout.

default: "apitome/application"

code_theme

We're using [highlight.js](https://github.com/isagalaev/highlight.js) for code highlighting, and it comes with some great themes. You can check [here for themes](http://softwaremaniacs.org/media/soft/highlight/test.html), and enter the theme as lowercase/underscore.

default: "default"

css_override

This allows you to override the css manually. You typically want to require `apitome/application` within the override, but if you want to override it entirely you can do so.

default: nil

js_override

This allows you to override the javascript manually. You typically want to require `apitome/application` within the override, but if you want to override it entirely you can do so.

default: nil

readme

You can provide a "README" style markdown file for the documentation, which is a useful place to include general information. This path is relative to your doc_path configuration.

default: "../api.md"

single_page

Apitome can render the documentation into a single page that uses scrollspy, or it can render the documentation on individual pages on demand. This allows you to specify which one you want, as a single page may impact performance.

default: true

url_formatter

You can specify how urls are formatted using a Proc or other callable object. Your proc will be called with a resource name or link, giving you the opportunity to modify it as necessary for in the documentation url.

default: -> (str) { str.gsub(/.json$/, '').underscore.gsub(/[^0-9a-z]+/i, '-') }

=======

When you install Apitime an initializer file (app/config/initializers/apitome.rb) is generated that contains good documentation for each configuration directive. Otherwise you can get a refresher by checking the Apitome Configuration article.

Customization

You can put custom views and partials in your own views/apitome/docs -- check the repo here for examples. You can put any partial in your own path and they will be overridden.

Additional customization can come in the form of providing custom css and javascript. You can do this by creating the files you want (that often times require the default assets in the gem), and then configure Apitome to use those instead of the defaults.

License

Licensed under the MIT License

Copyright 2013 Mode Set

Make Code Not War