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, 30 insertions, 49 deletions

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()