The Librato Api Docs
This is our API Docs site. It runs on Slate which is very easy to edit. The pages are hosted at https://www.librato.com/docs/api
About This Project
You can add/edit the docs using Markdown. CircleCI takes care of automating the process: anything that is merged into the master branch kicks off a build and is automagically shipped to production (hosted on S3).
Setting up Slate for the First Time
You're going to need:
- Linux or OS X — Windows may work, but is unsupported.
- Ruby, version 1.9.3 or newer
- Bundler — If Ruby is already installed, but the
bundlecommand doesn't work, just run
gem install bundlerin a terminal.
Getting Set Up
- Fork this repository on Github.
- Clone your forked repository (not our original one) to your hard drive with
git clone firstname.lastname@example.org:librato/api-docs.git
- Install all dependencies:
- Start the test server:
bundle exec middleman server
Or use the included Dockerfile! (must install Docker first)
docker build -t api-docs . docker run -d -p 4567:4567 --name api-docs -v $(pwd)/source:/app/source api-docs
You can now see the docs at http://localhost:4567.
Note: if you're using the Docker setup on OSX, the docs may be
availalable at the output of
local.docker:4567 instead of
Editing the Docs
All of the documentation can be edited in the Markdown files. In order to add content to the body, add a new file within the
/includes folder with new content. You will need to also specify this file in the
includes section within the main
For example, within
/index.md the section
- authentication is at the top of the
includes: section. It will reference the file
includes/_authentication.md. Since this is referenced first in the list it will be appended just after the content in
index.md when generating the single documentation page.
Learn more about editing Slate markdown.
H1 tags (
# in Markdown) are automatically added to the sidebar, and H2 tags (
##) are automatically added as sub-menu items.
Generally H2 tags are only used for CRUD (create/retrieve/update/delete) of an object, but other high priority sections can be added to H2 as well (eg. Pagination, List all Metrics).
The center column is used for all API documentation other than examples (which are reserved for the right column).
To highlight code in this column you can simply surround your code with backticks (``).
You can add a notice with the following HTML:
<aside class="notice">Note: Blah blah....</aside>
- Tables should be used when describing object properties. Here is an example of building a 2 column 3 row table:
Property | Definition -------- | ---------- start_time | Unix Time of where to start the time search from. This parameter is optional if duration is specified. end_time | Unix Time of where to end the search. This parameter is optional and defaults to current wall time. resolution<br>`required` | Defines the resolution to return the data to in seconds.
The right column is reserved for examples. To add examples to the right of a H1, H2, or H3 section, place the example code just below the header title. In order for examples to load on the right column, sentences will need to start with a
> or code blocks will need to be surrounded by 3 backticks. Text which you wish to have read in the center column should come just after the example code.
### Metric Measurement Queries >Retrieve all metrics containing `request` in the metric name: ``shell curl \ -i \ -u $LIBRATO_USERNAME:$LIBRATO_TOKEN \ -X GET \ 'https://metrics-api.librato.com/v1/metrics?name=request' `` Center column text here
In the example above, notice how '>' is used for any text you want to add in the example section, while 3 backticks around your codeblock will add syntax highlighting and set the code to the right column. You should specify
python after the opening backticks to specify the type of syntax highlighting that should be used.
You can also add code highlighting to specific words in the examples section by adding single backticks around the word(s). This is used mainly for highlighting object properties.
>Retrieve all metrics containing `request` in the metric name:
This project is deployed via CircleCI each time a PR is merged into master. Check Deploy status on CircleCI