Rework documentation

Gauvain Pocentek · Gauvain Pocentek · commit 1a7f67274c91 · 2017-06-18T12:16:08.000+02:00
diff --git a/docs/api/gitlab.rst b/docs/api/gitlab.rst
@@ -1,55 +1,48 @@
 gitlab package
 ==============
 
-Module contents
----------------
+Subpackages
+-----------
 
-.. automodule:: gitlab
+.. toctree::
+
+    gitlab.v3
+    gitlab.v4
+
+Submodules
+----------
+
+gitlab.base module
+------------------
+
+.. automodule:: gitlab.base
     :members:
     :undoc-members:
     :show-inheritance:
-    :exclude-members: Hook, UserProject, Group, Issue, Team, User,
-                      all_projects, owned_projects, search_projects
 
-gitlab.base
------------
+gitlab.cli module
+-----------------
 
-.. automodule:: gitlab.base
+.. automodule:: gitlab.cli
     :members:
     :undoc-members:
     :show-inheritance:
 
-gitlab.v3.objects module
-------------------------
+gitlab.config module
+--------------------
 
-.. automodule:: gitlab.v3.objects
+.. automodule:: gitlab.config
     :members:
     :undoc-members:
     :show-inheritance:
-    :exclude-members: Branch, Commit, Content, Event, File, Hook, Issue, Key,
-                      Label, Member, MergeRequest, Milestone, Note, Snippet,
-                      Tag, canGet, canList, canUpdate, canCreate, canDelete,
-                      requiredUrlAttrs, requiredListAttrs, optionalListAttrs,
-                      optionalGetAttrs, requiredGetAttrs, requiredDeleteAttrs,
-                      requiredCreateAttrs, optionalCreateAttrs,
-                      requiredUpdateAttrs, optionalUpdateAttrs, getRequiresId,
-                      shortPrintAttr, idAttr
 
-gitlab.v4.objects module
-------------------------
+gitlab.const module
+-------------------
 
-.. automodule:: gitlab.v4.objects
+.. automodule:: gitlab.const
     :members:
     :undoc-members:
     :show-inheritance:
-    :exclude-members: Branch, Commit, Content, Event, File, Hook, Issue, Key,
-                      Label, Member, MergeRequest, Milestone, Note, Snippet,
-                      Tag, canGet, canList, canUpdate, canCreate, canDelete,
-                      requiredUrlAttrs, requiredListAttrs, optionalListAttrs,
-                      optionalGetAttrs, requiredGetAttrs, requiredDeleteAttrs,
-                      requiredCreateAttrs, optionalCreateAttrs,
-                      requiredUpdateAttrs, optionalUpdateAttrs, getRequiresId,
-                      shortPrintAttr, idAttr
 
 gitlab.exceptions module
 ------------------------
@@ -58,3 +51,28 @@ gitlab.exceptions module
     :members:
     :undoc-members:
     :show-inheritance:
+
+gitlab.mixins module
+--------------------
+
+.. automodule:: gitlab.mixins
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+gitlab.utils module
+-------------------
+
+.. automodule:: gitlab.utils
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: gitlab
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/api/modules.rst b/docs/api/modules.rst
diff --git a/docs/ext/docstrings.py b/docs/ext/docstrings.py
@@ -10,6 +10,8 @@
 
 
 def classref(value, short=True):
+    return value
+
     if not inspect.isclass(value):
         return ':class:%s' % value
     tilde = '~' if short else ''
@@ -46,8 +48,13 @@ def _build_doc(self, tmpl, **kwargs):
 
         return output.split('\n')
 
-    def __init__(self, *args, **kwargs):
-        super(GitlabDocstring, self).__init__(*args, **kwargs)
+    def __init__(self, docstring, config=None, app=None, what='', name='',
+                 obj=None, options=None):
+        super(GitlabDocstring, self).__init__(docstring, config, app, what,
+                                              name, obj, options)
+
+        if name and name.startswith('gitlab.v4.objects'):
+            return
 
         if getattr(self._obj, '__name__', None) == 'Gitlab':
             mgrs = []
@@ -57,9 +64,12 @@ def __init__(self, *args, **kwargs):
                     mgrs.append(item)
             self._parsed_lines.extend(self._build_doc('gl_tmpl.j2',
                                                       mgrs=sorted(mgrs)))
+
+        # BaseManager
         elif hasattr(self._obj, 'obj_cls') and self._obj.obj_cls is not None:
             self._parsed_lines.extend(self._build_doc('manager_tmpl.j2',
                                                       cls=self._obj.obj_cls))
+        # GitlabObject
         elif hasattr(self._obj, 'canUpdate') and self._obj.canUpdate:
             self._parsed_lines.extend(self._build_doc('object_tmpl.j2',
                                                       obj=self._obj))
diff --git a/docs/index.rst b/docs/index.rst
@@ -16,7 +16,7 @@ Contents:
    api-usage
    switching-to-v4
    api-objects
-   api/modules
+   api/gitlab
    release_notes
    changelog
 
diff --git a/gitlab/v4/objects.py b/gitlab/v4/objects.py
@@ -996,10 +996,6 @@ class ProjectMilestoneManager(RetrieveMixin, CreateMixin, DeleteMixin,
 class ProjectLabel(SubscribableMixin, SaveMixin, ObjectDeleteMixin,
                    RESTObject):
     _id_attr = 'name'
-    requiredCreateAttrs = ['name', 'color']
-    optionalCreateAttrs = ['description', 'priority']
-    requiredUpdateAttrs = ['name']
-    optionalUpdateAttrs = ['new_name', 'color', 'description', 'priority']
 
 
 class ProjectLabelManager(GetFromListMixin, CreateMixin, UpdateMixin,
