Docs

Docs is a documentation generator for Ruby. It is intended for documenting things like HTTP APIs where the documentation doesn't make sense within the code.

Install

gem install docs

Setup

To setup Docs, run the following in an empty directory:

docs setup

It will create the following file structure:

• docs/
• examples/
• config.yaml
• application.erb

The docs directory contains your documentation (written in Markdown, using the .mdown file extension), these are compiled to HTML at build time. The Markdown files are pre-processed with ERB, primarily so you can include your examples (up next).

The examples directory contains the examples used within your code. The source of these files is made available to all documentation files at build time. If the files are written in either BASH or Ruby, using the .sh and .rb extensions, respesctively, the output of these scripts when run is also made available. These are stored outside of the actual documentation so you can test them (ensuring you don't ship bad docs!).

You can specify that an example is preprocessed with ERB by prefixing its actual file extension with .erb. e.g. examples/create_a_user.sh would become examples/create_a_user.erb.sh. This is useful for including config variables set in config.yaml (see below).

To include the source of an example named examples/create_a_user.sh:

<%= examples :source, 'examples/create_a_user.sh' %>

If you would like to show the output:

<%= examples :output, 'examples/create_a_user.sh' %>

The config.yaml file contains some config variables for Docs. Any variable set here is accessible within your documentation and within examples pre-processed with ERB:

<%= config.template %>

config.yaml also supports environment dependent variables. These are useful for setting things like your API endpoint, so you can compile the docs locally or against production. e.g.

environment:
  production:
    api_endpoint: "http://api.intercom.io/"
  development:
    api_endpoint: "http://intercom.dev"

The default environment is production, to change the environment set the value of the DOCS_ENV environment variable. In the example above if docs was run in the production environment, api_endpoint would be set as a top level attribute in config and the variables set in development would be inaccessible. e.g.

<%= config.api_endpoint %>

If template is set in config.yaml, all markdown files will be compiled with template used as the template. Within the template you can include the compiled Markdown:

<%= content %>

There are a few helpers made available to documentation files:

• pretty_print_json(string) — This takes a JSON string and pretty prints it.
• syntax_highlight(string, language) — Takes any piece of code and syntax highlights it with CodeRay, language is a Symbol representing one of CodeRay's supported languages.

Building

To build a Docs project:

docs build