foliantcontrib.ramldoc 1.0.0

Documentation generator for RAML API

RAML API Docs Generator for Foliant

This preprocessor generates Markdown documentation from RAML spec files. It uses raml2html converter with raml2html-full-markdown-theme.

raml2html uses Nunjucks templating system.

Installation

First install raml2html and the markdown theme:

$ npm install -g raml2html raml2html-full-markdown-theme

Then install the preprocessor:

$ pip install foliantcontrib.ramldoc

Config

To enable the preprocessor, add ramldoc to preprocessors section in the project config:

preprocessors:
    - ramldoc

The preprocessor has a number of options:

preprocessors:
    - ramldoc:
        spec_url: http://localhost/my_api.raml
        spec_path: !path my_api.raml
        template_dir: !path custom_templates
        raml2html_path: raml2html

spec_url : URL to RAML spec file. If it is a list — preprocessor picks the first working URL.

spec_path : Local path to RAML spec file.

If both URL and path are specified — preprocessor first tries to fetch spec from URL, and then (if that fails) looks for the file on local path.

template_dir : Path to directory with Nunjucks templates. If not specified — default template is used. The main template in the directory must have a name root.nunjucks.

raml2html_path : Path to raml2html binary. Default: raml2html

Usage

Add a <ramldoc></ramldoc> tag at the position in the document where the generated documentation should be inserted:

# Introduction

This document contains the automatically generated documentation of our API.

<ramldoc></ramldoc>

Each time the preprocessor encounters the tag <ramldoc></ramldoc> it inserts the whole generated documentation text instead of it. The path or url to RAML spec file are taken from foliant.yml.

You can also specify some parameters (or all of them) in the tag options:

# Introduction

Introduction text for API documentation.

<ramldoc spec_url="http://localhost/my_api.raml"
         template_dir="assets/templates">
</ramldoc>

Tag parameters have the highest priority.

This way you can have documentation from several different RAML spec files in one Foliant project (even in one md-file if you like it so).

Customizing output

The output markdown is generated by raml2html converter, which uses Nunjucks templating engine (with syntax similar to Jinja2. If you want to create your own template or modify the default one, specify the template_dir parameter.

The main template file in template dir must be named root.nunjucks.

You may use the default template as your starting point.