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.
gem install docs
To setup Docs, run the following in an empty directory:
It will create the following file structure:
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).
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
.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
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 :source, 'examples/create_a_user.sh' %>
If you would like to show the output:
<%= examples :output, 'examples/create_a_user.sh' %>
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.
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
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 %>
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.
To build a Docs project: