RaaS API Docs

The RaaS API documentation is generated using the Jekyll tool. This tool allows you to generate html files using markdown format files.

This model was built by CloudCannon.

Steps to start working on the documentation

1. Install Ruby+Devkit
2. Install Jekyll
3. Clone the project

Changes to current documentation

To add a new section to the documentation or to modify an existing section, simply add or modify a markdown file in one of the folders representing a collection.

The current documentation contains the following three collections

• Documentation
• API
• Appendix

In order for the file to be processed by Jekyll, it must start with a front matter block. See the files currently in place as an example or the following documentation

Jekyll Front Matter

Note: Do not work on or make changes to files located in the _site folder. These are the files generated by Jekyll, so all changes made to files located in this folder will be lost when the server is started.

Documentation collection structure information

• Each section of the documentation is a different collection. This helps organize the content.
• The order of the collections is determined by the position_number fields in the collection configuration in the _config.yml file.
• The order of items in a collection is determined by the position_number field in a front matter block in a markdown file, e.g. introduction.md.

Start the server

Install the Gemfile dependencies with Bundler:

bundle install

To quickly see the changes made at http://localhost:4000, run the following Jekyll command using Bundle:

$ bundle exec jekyll serve

Deployment of Changes

The site is deployed onto Netlify via a continuous deployment process which just requires a push to the main branch to publish new changes.

When adding changes to the site, first open a pull request. Netlify will automatically deploy a separate site to preview the changes in the PR. Information on preview site, including URL, will be automatically added to the PR as a comment.