Skip to content

Commit 194ed0b

Browse files
author
Gauvain Pocentek
committed
[docs] update the sphinx extension for v4 objects
1 parent 5292ffb commit 194ed0b

File tree

4 files changed

+32
-132
lines changed

4 files changed

+32
-132
lines changed

docs/ext/docstrings.py

Lines changed: 2 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -53,23 +53,6 @@ def __init__(self, docstring, config=None, app=None, what='', name='',
5353
super(GitlabDocstring, self).__init__(docstring, config, app, what,
5454
name, obj, options)
5555

56-
if name and name.startswith('gitlab.v4.objects'):
57-
return
58-
59-
if getattr(self._obj, '__name__', None) == 'Gitlab':
60-
mgrs = []
61-
gl = self._obj('http://dummy', private_token='dummy')
62-
for item in vars(gl).items():
63-
if hasattr(item[1], 'obj_cls'):
64-
mgrs.append(item)
65-
self._parsed_lines.extend(self._build_doc('gl_tmpl.j2',
66-
mgrs=sorted(mgrs)))
67-
68-
# BaseManager
69-
elif hasattr(self._obj, 'obj_cls') and self._obj.obj_cls is not None:
56+
if name.startswith('gitlab.v4.objects') and name.endswith('Manager'):
7057
self._parsed_lines.extend(self._build_doc('manager_tmpl.j2',
71-
cls=self._obj.obj_cls))
72-
# GitlabObject
73-
elif hasattr(self._obj, 'canUpdate') and self._obj.canUpdate:
74-
self._parsed_lines.extend(self._build_doc('object_tmpl.j2',
75-
obj=self._obj))
58+
cls=self._obj))

docs/ext/gl_tmpl.j2

Lines changed: 0 additions & 5 deletions
This file was deleted.

docs/ext/manager_tmpl.j2

Lines changed: 30 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -1,84 +1,38 @@
1-
Manager for {{ cls | classref() }} objects.
2-
3-
{% if cls.canUpdate %}
4-
{{ cls | classref() }} objects can be updated.
5-
{% else %}
6-
{{ cls | classref() }} objects **cannot** be updated.
1+
{% if cls._list_filters %}
2+
**Object listing filters**
3+
{% for item in cls._list_filters %}
4+
- ``{{ item }}``
5+
{% endfor %}
76
{% endif %}
87

9-
{% if cls.canList %}
10-
.. method:: list(**kwargs)
11-
12-
Returns a list of objects of type {{ cls | classref() }}.
13-
14-
Available keys for ``kwargs`` are:
15-
16-
{% for k in cls.requiredListAttrs %}
17-
* ``{{ k }}`` (required)
18-
{% endfor %}
19-
{% for k in cls.optionalListAttrs %}
20-
* ``{{ k }}`` (optional)
21-
{% endfor %}
22-
* ``per_page`` (int): number of item per page. May be limited by the server.
23-
* ``page`` (int): page to retrieve
24-
* ``all`` (bool): iterate over all the pages and return all the entries
25-
* ``sudo`` (string or int): run the request as another user (requires admin
26-
permissions)
8+
{% if cls._create_attrs %}
9+
**Object Creation**
10+
{% if cls._create_attrs[0] %}
11+
Mandatory attributes:
12+
{% for item in cls._create_attrs[0] %}
13+
- ``{{ item }}``
14+
{% endfor %}
2715
{% endif %}
28-
29-
{% if cls.canGet %}
30-
{% if cls.getRequiresId %}
31-
.. method:: get(id, **kwargs)
32-
33-
Get a single object of type {{ cls | classref() }} using its ``id``.
34-
{% else %}
35-
.. method:: get(**kwargs)
36-
37-
Get a single object of type {{ cls | classref() }}.
16+
{% if cls._create_attrs[1] %}
17+
Optional attributes:
18+
{% for item in cls._create_attrs[1] %}
19+
- ``{{ item }}``
20+
{% endfor %}
3821
{% endif %}
39-
40-
Available keys for ``kwargs`` are:
41-
42-
{% for k in cls.requiredGetAttrs %}
43-
* ``{{ k }}`` (required)
44-
{% endfor %}
45-
{% for k in cls.optionalGetAttrs %}
46-
* ``{{ k }}`` (optional)
47-
{% endfor %}
48-
* ``sudo`` (string or int): run the request as another user (requires admin
49-
permissions)
5022
{% endif %}
5123

52-
{% if cls.canCreate %}
53-
.. method:: create(data, **kwargs)
54-
55-
Create an object of type {{ cls | classref() }}.
56-
57-
``data`` is a dict defining the object attributes. Available attributes are:
58-
59-
{% for a in cls.requiredUrlAttrs %}
60-
* ``{{ a }}`` (required if not discovered on the parent objects)
61-
{% endfor %}
62-
{% for a in cls.requiredCreateAttrs %}
63-
* ``{{ a }}`` (required)
64-
{% endfor %}
65-
{% for a in cls.optionalCreateAttrs %}
66-
* ``{{ a }}`` (optional)
67-
{% endfor %}
68-
69-
Available keys for ``kwargs`` are:
70-
71-
* ``sudo`` (string or int): run the request as another user (requires admin
72-
permissions)
24+
{% if cls._update_attrs %}
25+
**Object update**
26+
{% if cls._update_attrs[0] %}
27+
Mandatory attributes for object update:
28+
{% for item in cls._update_attrs[0] %}
29+
- ``{{ item }}``
30+
{% endfor %}
31+
{% endif %}
32+
{% if cls._update_attrs[1] %}
33+
Optional attributes for object update:
34+
{% for item in cls._update_attrs[1] %}
35+
- ``{{ item }}``
36+
{% endfor %}
7337
{% endif %}
74-
75-
{% if cls.canDelete %}
76-
.. method:: delete(id, **kwargs)
77-
78-
Delete the object with ID ``id``.
79-
80-
Available keys for ``kwargs`` are:
81-
82-
* ``sudo`` (string or int): run the request as another user (requires admin
83-
permissions)
8438
{% endif %}

docs/ext/object_tmpl.j2

Lines changed: 0 additions & 32 deletions
This file was deleted.

0 commit comments

Comments
 (0)