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.

6 files changed, 146 insertions, 79 deletions

diff --git a/docs/api/gitlab.rst b/docs/api/gitlab.rst
index 37997be..72796ee 100644
--- a/docs/api/gitlab.rst
+++ b/docs/api/gitlab.rst
@@ -28,4 +28,9 @@ gitlab.objects module
     :show-inheritance:
     :exclude-members: Branch, Commit, Content, Event, File, Hook, Issue, Key,
                       Label, Member, MergeRequest, Milestone, Note, Snippet,
-                      Tag
+                      Tag, canGet, canList, canUpdate, canCreate, canDelete,
+                      requiredUrlAttrs, requiredListAttrs, optionalListAttrs,
+                      optionalGetAttrs, requiredGetAttrs, requiredDeleteAttrs,
+                      requiredCreateAttrs, optionalCreateAttrs,
+                      requiredUpdateAttrs, optionalUpdateAttrs, getRequiresId,
+                      shortPrintAttr, idAttr
diff --git a/docs/ext/docstrings.py b/docs/ext/docstrings.py
index 4520e43..cd019ee 100644
--- a/docs/ext/docstrings.py
+++ b/docs/ext/docstrings.py
@@ -8,6 +8,11 @@ import sphinx.ext.napoleon as napoleon
 from sphinx.ext.napoleon.docstring import GoogleDocstring
 
 
+def classref(value, short=True):
+    tilde = '~' if short else ''
+    return ':class:`%sgitlab.objects.%s`' % (tilde, value.__name__)
+
+
 def setup(app):
     app.connect('autodoc-process-docstring', _process_docstring)
     app.connect('autodoc-skip-member', napoleon._skip_member)
@@ -28,58 +33,34 @@ def _process_docstring(app, what, name, obj, options, lines):
 
 
 class GitlabDocstring(GoogleDocstring):
-    def _build_doc(self):
-        cls = self._obj.obj_cls
-        opt_get_list = cls.optionalGetAttrs
-        opt_list_list = cls.optionalListAttrs
-        md_create_list = list(itertools.chain(cls.requiredUrlAttrs,
-                                              cls.requiredCreateAttrs))
-        opt_create_list = cls.optionalCreateAttrs
-
-        opt_get_keys = "None"
-        if opt_get_list:
-            opt_get_keys = ", ".join(['``%s``' % i for i in opt_get_list])
-
-        opt_list_keys = "None"
-        if opt_list_list:
-            opt_list_keys = ", ".join(['``%s``' % i for i in opt_list_list])
-
-        md_create_keys = opt_create_keys = "None"
-        if md_create_list:
-            md_create_keys = ", ".join(['``%s``' % i for i in md_create_list])
-        if opt_create_list:
-            opt_create_keys = ", ".join(['``%s``' % i for i in
-                                         opt_create_list])
-
-        md_update_list = list(itertools.chain(cls.requiredUrlAttrs,
-                                              cls.requiredUpdateAttrs))
-        opt_update_list = cls.optionalUpdateAttrs
-
-        md_update_keys = opt_update_keys = "None"
-        if md_update_list:
-            md_update_keys = ", ".join(['``%s``' % i for i in md_update_list])
-        if opt_update_list:
-            opt_update_keys = ", ".join(['``%s``' % i for i in
-                                         opt_update_list])
-
-        tmpl_file = os.path.join(os.path.dirname(__file__), 'template.j2')
-        with open(tmpl_file) as fd:
-            template = jinja2.Template(fd.read(), trim_blocks=False)
-            output = template.render(filename=tmpl_file,
-                                     cls=cls,
-                                     md_create_keys=md_create_keys,
-                                     opt_create_keys=opt_create_keys,
-                                     md_update_keys=md_update_keys,
-                                     opt_update_keys=opt_update_keys,
-                                     opt_get_keys=opt_get_keys,
-                                     opt_list_keys=opt_list_keys)
+    _j2_env = None
+
+    def _build_j2_env(self):
+        if self._j2_env is None:
+            self._j2_env = jinja2.Environment(loader=jinja2.FileSystemLoader(
+                os.path.dirname(__file__)), trim_blocks=False)
+            self._j2_env.filters['classref'] = classref
+
+        return self._j2_env
+
+    def _build_manager_doc(self):
+        env = self._build_j2_env()
+        template = env.get_template('manager_tmpl.j2')
+        output = template.render(cls=self._obj.obj_cls)
+
+        return output.split('\n')
+
+    def _build_object_doc(self):
+        env = self._build_j2_env()
+        template = env.get_template('object_tmpl.j2')
+        output = template.render(obj=self._obj)
 
         return output.split('\n')
 
     def __init__(self, *args, **kwargs):
         super(GitlabDocstring, self).__init__(*args, **kwargs)
 
-        if not hasattr(self._obj, 'obj_cls') or self._obj.obj_cls is None:
-            return
-
-        self._parsed_lines = self._build_doc()
+        if hasattr(self._obj, 'obj_cls') and self._obj.obj_cls is not None:
+            self._parsed_lines = self._build_manager_doc()
+        elif hasattr(self._obj, 'canUpdate') and self._obj.canUpdate:
+            self._parsed_lines = self._build_object_doc()
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 %}
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)
diff --git a/docs/ext/template.j2 b/docs/ext/template.j2
deleted file mode 100644
index 29f4a00..0000000
--- a/docs/ext/template.j2
+++ /dev/null
@@ -1,29 +0,0 @@
-Manager for :class:`gitlab.objects.{{ cls.__name__ }}` objects.
-
-Available actions for this class:
-
-{% if cls.canList %}- Objects listing{%endif%}
-{% if cls.canGet %}- Unique object retrieval{%endif%}
-{% if cls.canCreate %}- Object creation{%endif%}
-{% if cls.canUpdate %}- Object update{%endif%}
-{% if cls.canDelete %}- Object deletion{%endif%}
-
-{% if cls.canCreate %}
-Mandatory arguments for object creation: {{ md_create_keys }}
-
-Optional arguments for object creation:  {{ opt_create_keys }}
-{% endif %}
-
-{% if cls.canUpdate %}
-Mandatory arguments for object update: {{ md_create_keys }}
-
-Optional arguments for object update: {{ opt_create_keys }}
-{% endif %}
-
-{% if cls.canList %}
-Optional arguments for object listing: {{ opt_list_keys }}
-{% endif %}
-
-{% if cls.canGet %}
-Optional arguments for object listing: {{ opt_get_keys }}
-{% endif %}
diff --git a/test-requirements.txt b/test-requirements.txt
index 25cb7dd..65d09d7 100644
--- a/test-requirements.txt
+++ b/test-requirements.txt
@@ -6,3 +6,4 @@ httmock
 jinja2
 mock
 sphinx>=1.3
+sphinx_rtd_theme