Refactor all API v2 docstrings

As API v1 tests will be rewritten the rafactor could happen when
updating the tests.
Merge pull request #1327 from elyezer/docstring-refactor-api-v2

Refactor all API v2 docstrings
Fix four errors emitted by `sphinx make-docs`
Merge pull request #1328 from Ichimonji10/sphinx

Fix four errors emitted by `sphinx make-docs`
Flesh out ComputeResource entity, test it.

When creating a new "compute resource" entity, a variable set of values must be
provided to the Foreman server. The exact set of values depends on the specified
provider. (e.g. EC2, Rackspace, etc.) Flesh out the ComputeResource entity with
logic necessary for handling this variability in requirements.

Add some API tests for the ComputeResource entity All tests for the
ComputeResource currently fail. These tests fail for a variety of reasons. For
example:

* Creating a compute resource with a provider of 'Rackspace' causes Foreman to
  throw an HTTP 500 with the message "undefined method `upcase' for
  nil:NilClass".
* Creating a compute resource with a provider of 'GCE' fails because Foreman
  needs more data. However, the types of data needed are not discussed in the
  API docs.
* Creating a compute resource with several other providers causes Foreman to
  return the following error: "getaddrinfo: Name or service not known".

These issues should be tackled by someone who knows more about compute
resources.