+-----------------------------------------------------------------------------+
Building

From this directory, run:

  make clean && make html

The built documentation will be under _build/html

+-----------------------------------------------------------------------------+
reST Cheatsheet

Below are a few useful commands to know:
* Bold is gotten by wrapping the text with double *. Example: **awesome**
* Italics is wrapped with single *. Example: *rock*
* A link to the glossary is done using the :term: role. The value of the role
  is the text to include as the link and then the actual target in the glossary.
  For example: :term:`distributors <distributor>` will name the link "distributors"
  and reference the distributor entry in the glossary.
* Adding an entry in the glossary is very simple, just follow the format of an
  existing item in glossary.rst.

+-----------------------------------------------------------------------------+
API Pages

APIs should be divided into logical groupings to keep from making pages too
long and cumbersome to deal with. The page title should be rendered as a reST
section using = as the underline. For example:

Creation and Configuration
==========================

Each individual API then uses - as the underline:

Create a Repository
-------------------

+-----------------------------------------------------------------------------+
API Template

Below is the template used for a single API. Things to keep in mind:

* For response_list and sample_request, the `_` part is required.
* For sample_request, make sure to have a space after the ` and before ::
* Variables in a path are denoted by <> (e.g. /repositories/<repo_id>/)
* Order response codes in ascending order
* A ? at the start of a param name will flag it as optional
* param_list takes the method value as an argument
* sample_response takes the code of the response being sampled

See ../extensions/rest_api.py for the implementations of each role used in the
template below. The docstrings for each role method describe the format of the
values to pass to each role.



API TITLE
---------

DESCRIPTION

BLANK LINES BETWEEN MULTIPLE PARAGRAPHS

| :method:`post`
| :path:`/v2/repositories/<id>/`
| :permission:`create`
| :param_list:`post`

* :param:`id,str,unique identifier for the repository`
* :param:`?display_name,str,user-friendly name for the repository`

| :response_list:`_`

* :response_code:`201,if the repository was created`
* :response_code:`409,if a repository already exists with the given ID`

| :return:`serialized version of the created repository`

:sample_request:`_` ::

 {
  "display_name": "Harness Repository: harness_repo_1",
  "id": "harness_repo_1"
 }

:sample_response:`200` ::

 {
  "display_name": "Harness Repository: harness_repo_1",
  "description": null,
  "_ns": "gc_repositories",
  "notes": {},
  "content_unit_count": 0,
  "_id": "harness_repo_1",
  "id": "harness_repo_1"
 }