The docs themselves are available at https://cloud-ca.github.io/api-docs
You're going to need:
- Linux or OS X — Windows may work, but is unsupported.
- Ruby, version 2.0 or newer
- Bundler — If Ruby is already installed, but the
bundlecommand doesn't work, just rungem install bundlerin a terminal.
brew install rubyto upgrade your Ruby installgem install bundlergit clone git@github.com:cloud-ca/api-docs.gitcd api-docs- 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 upYou can now see the docs at http://localhost:4567. Whoa! That was fast!
Now that Slate is all set up 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.
The main place to set up your includes is source/index.html.md. The includes themselves are in source/includes and must start with an underscore. Only one level of folder nesting is currently supported for includes (eg. compute/instances.md, but not services/compute/instances.md).
When writing new docs, put them in their own branch and merge them back into master.
TODO: update with instructions on deploying the docs with jenkins
- Make sure your changes have been merged into
master git checkout deploymentgit merge master./deploy.sh
The docs should go live once GitHub processes the new gh-pages branch contents.