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, 25 insertions, 0 deletions

diff --git a/docs/ext/object_tmpl.j2 b/docs/ext/object_tmpl.j2
new file mode 100644
index 0000000..327eafb
--- /dev/null
+++ b/docs/ext/object_tmpl.j2
@@ -0,0 +1,25 @@
+.. method:: save(**kwargs)
+
+   Send the modified object to the GitLab server. The following attributes are
+   sent:
+
+{% if obj.requiredUpdateAttrs or obj.optionalUpdateAttrs %}
+   {% for a in obj.requiredUpdateAttrs %}
+   * ``{{ a }}`` (required)
+   {% endfor %}
+   {% for a in obj.optionalUpdateAttrs %}
+   * ``{{ a }}`` (optional)
+   {% endfor %}
+{% else %}
+   {% for a in obj.requiredCreateAttrs %}
+   * ``{{ a }}`` (required)
+   {% endfor %}
+   {% for a in obj.optionalCreateAttrs %}
+   * ``{{ a }}`` (optional)
+   {% endfor %}
+{% endif %}
+
+   Available keys for ``kwargs`` are:
+
+   * ``sudo`` (string or int): run the request as another user (requires admin
+     permissions)