cloud.ca API docs

The docs themselves are available at https://cloud-ca.github.io/api-docs

Getting Started with Slate

Prerequisites

You're going to need:

• Linux or macOS — Windows may work, but is unsupported.
• Ruby, version 2.3.1 or newer
• Bundler — If Ruby is already installed, but the bundle command doesn't work, just run gem install bundler in a terminal.

Getting Set Up

1. brew install ruby to upgrade your Ruby install
2. gem install bundler
3. git clone [email protected]:cloud-ca/api-docs.git
4. cd api-docs
5. Initialize and start Slate. You can either do this locally, or with Vagrant:

# either run this to run locally
bundle install
bundle exec middleman server

# OR run this to run with vagrant
vagrant up

You can now see the docs at http://localhost:4567. Whoa! That was fast!

Now that Slate is all set up on your machine, you'll probably want to learn more about editing Slate markdown, or how to publish your docs.

If you'd prefer to use Docker, instructions are available in the wiki.

Working on the docs

The main place to set up your includes is source/index.html.md. The content of the includes themselves are in source/includes, and the filenames must start with an underscore. Slate by default supports only one level of folder nesting. We have added support for one level of subsections within an include (eg. compute/_instances.md, but not services/compute/_instances.md) by defining a subsection element. The commit for the definition is here. The subsections element is used in source/index.html.md:

includes:
  - getting_started
  - administration
  - compute

subsections:
  administration:
    - service_connections
    - organizations
    - users
    - environments
    - usage
  compute:
    - compute 
    - instances
    - templates

When writing new docs, put them in their own branch and merge them back into master.

Deploying

TODO: update with instructions on deploying the docs with jenkins

1. Make sure your changes have been merged into master
2. git checkout deployment
3. git merge master
4. ./deploy.sh

The docs should go live once GitHub processes the new gh-pages branch contents.