Rework the API documentation

Update the sphinx extension to add method definition in the docs. This
makes the documentation a bit more usable.

Hide attributes that should not have been exposed. They still exist in
the code but their documentation doesn't make much sense.

1 files changed, 84 insertions, 0 deletions

diff --git a/docs/ext/manager_tmpl.j2 b/docs/ext/manager_tmpl.j2
new file mode 100644
index 0000000..a8b4686
--- /dev/null
+++ b/docs/ext/manager_tmpl.j2
@@ -0,0 +1,84 @@
+Manager for {{ cls | classref() }} objects.
+
+{% if cls.canUpdate %}
+{{ cls | classref() }} objects can be updated.
+{% else %}
+{{ cls | classref() }} objects **cannot** be updated.
+{% endif %}
+
+{% if cls.canList %}
+.. method:: list(**kwargs)
+
+   Returns a list of objects of type {{ cls | classref() }}.
+
+   Available keys for ``kwargs`` are:
+
+   {% for k in cls.requiredListAttrs %}
+   * ``{{ k }}`` (required)
+   {% endfor %}
+   {% for k in cls.optionalListAttrs %}
+   * ``{{ k }}`` (optional)
+   {% endfor %}
+   * ``per_page`` (int): number of item per page. May be limited  by the server.
+   * ``page`` (int): page to retrieve
+   * ``all`` (bool): iterate over all the pages and return all the entries
+   * ``sudo`` (string or int): run the request as another user (requires admin
+     permissions)
+{% endif %}
+
+{% if cls.canGet %}
+{% if cls.getRequiresId %}
+.. method:: get(id, **kwargs)
+
+   Get a single object of type {{ cls | classref() }} using its ``id``.
+{% else %}
+.. method:: get(**kwargs)
+
+   Get a single object of type {{ cls | classref() }}.
+{% endif %}
+
+   Available keys for ``kwargs`` are:
+
+   {% for k in cls.requiredGetAttrs %}
+   * ``{{ k }}`` (required)
+   {% endfor %}
+   {% for k in cls.optionalGetAttrs %}
+   * ``{{ k }}`` (optional)
+   {% endfor %}
+   * ``sudo`` (string or int): run the request as another user (requires admin
+     permissions)
+{% endif %}
+
+{% if cls.canCreate %}
+.. method:: create(data, **kwargs)
+
+   Create an object of type {{ cls | classref() }}.
+
+   ``data`` is a dict defining the object attributes. Available attributes are:
+
+   {% for a in cls.requiredUrlAttrs %}
+   * ``{{ a }}`` (required)
+   {% endfor %}
+   {% for a in cls.requiredUrlAttrs %}
+   * ``{{ a }}`` (required if not discovered on the parent objects)
+   {% endfor %}
+   {% for a in cls.optionalCreateAttrs %}
+   * ``{{ a }}`` (optional)
+   {% endfor %}
+
+   Available keys for ``kwargs`` are:
+
+   * ``sudo`` (string or int): run the request as another user (requires admin
+     permissions)
+{% endif %}
+
+{% if cls.canDelete %}
+.. method:: delete(id, **kwargs)
+
+   Delete the object with ID ``id``.
+
+   Available keys for ``kwargs`` are:
+
+   * ``sudo`` (string or int): run the request as another user (requires admin
+     permissions)
+{% endif %}