RubberDoc

Table of Contents

• What is RubberDoc
• Installation
  • Using the release
  • Using the source
• Configuration
• Usage
• Help
• Examples
• Contribute
• CREDITS

What is RubberDoc

RubberDoc was designed to support api's documentation generation based on RAML and Blueprint.

Installation

The latest executables for supported platforms are available from the release page.

Using the release

Just extract and start using it:

$ wget https://github.com/rocket-internet-berlin/RocketLabsRubberDoc/releases/download/${version}/rubberdoc-${version}.${os}-${arch}.tar.gz
$ tar -zxvf rubberdoc-${version}.${os}-${arch}.tar.gz
$ ./rubberdoc -h

Using the source

$ git clone https://github.com/rocket-internet-berlin/RocketLabsRubberDoc.git
$ cd RocketLabsRubberDoc
$ make install

Note: Ensure you have installed Go and configured your GOPATH and PATH.

Configuration

The configuration is used to provide to the generator the location os the templates and how the will be generate and also the output's destination.

Global

Property	Description
combined	The option is a flag (true or false) and allows you to decide if the output will be combined in one file or will be located in different files defined on the Templates configuration.
srcDir	Defines the location of the templates. If a relative path is given then the absolute path will be resolved using the config's file absolute's path.
dstDir	Defines the output directory. If a relative path is given then the absolute path will be resolved using the config's file absolute's path.
output	Destination of the combined output. In case the combined property is true, this property should be set.
templates	Configuration for each template. See section Templates below.

Templates

Property	Description
src	Template's location.
dst	Templates's output destination. This property will be omitted when the combined property is set to true.

This example shows an configuration for a single template -> output:

combined: false
srcDir: "__TEMPLATES_SOURCE_DIRECTORY__"
dstDir: "__OUTPUT_DESTINATION_DIRECTORY__"
templates:
  -
    src: "simple.tmpl"
    dst: "simple.html"

This example shows an configuration for a multiple templates -> output.

combined: true
srcDir: "__TEMPLATES_SOURCE_DIRECTORY__"
dstDir: "__OUTPUT_DESTINATION_DIRECTORY__"
output: "__OUTPUT_FILENAME__"
templates:
  -
    src: "base.tmpl"
  -
    src: "title.tmpl"
  -
    src: "version.tmpl"
  -
    src: "baseUri.tmpl"
  -
    src: "protocols.tmpl"
  -
    src: "mediaTypes.tmpl"

To see how the configuration looks like, you can see it for the try-it-out located in try-it-out/templates/config.yaml.

Usage

HTML from a RAML's specification:

$ rubberdoc generate --spec=API.raml --config=config.yml

HTML from a Blueprint's specification:

$ rubberdoc generate --spec=API.apib --config=config.yml

Note: Check Configuration section to how to build your config.yml file.

Help

As usual, you can also see all supported flags by passing -h:

NAME:
   RubberDoc - A documentation generator for RAML and Blueprint

USAGE:
   rubberdoc [global options] command [command options] [arguments...]

VERSION:
   v0.1-alpha-2

DESCRIPTION:
   Documentation's generator for RAML and Blueprint.

COMMANDS:
     generate  This command receives a configuration file and a specification file written in RAML or Blueprint.
     help, h   Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --debug, -d    Enable debug logging
   --help, -h     show help
   --version, -v  print the version

Examples

Using RAML's specification:

$ rubberdoc generate --spec=examples/spec/raml/simple.raml --config=try-it-out/templates/config.yaml

Using Blueprint's specification:

$ rubberdoc generate --spec=examples/spec/blueprint/simple.apib --config=try-it-out/templates/config.yaml

Contribute

When you want to contribute to the development, follow the contribution guidelines.

CREDITS

• Jumpscale/go-raml for the raml parser.
• apiaryio/drafter for the Drafter library used by blueprint parser.
• Sirupsen/logrus for the logging library.
• urfave/cli for the cli library.
• stretchr/testify for the Assert package.