Skip to main content

Documentation generator for RAML API

Project description

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.


First install raml2html and the markdown theme:

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

Then install the preprocessor:

$ pip install foliantcontrib.ramldoc


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

    - ramldoc

The preprocessor has a number of options:

    - 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


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.


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"

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.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

foliantcontrib.ramldoc-1.0.2.tar.gz (5.2 kB view hashes)

Uploaded Source

Built Distribution

foliantcontrib.ramldoc-1.0.2-py3-none-any.whl (5.3 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page