Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commitbe83ff9

Browse files
author
Gauvain Pocentek
committed
Rework the API documentation
Update the sphinx extension to add method definition in the docs. Thismakes the documentation a bit more usable.Hide attributes that should not have been exposed. They still exist inthe code but their documentation doesn't make much sense.
1 parent9f7f45f commitbe83ff9

File tree

6 files changed

+146
-79
lines changed

6 files changed

+146
-79
lines changed

‎docs/api/gitlab.rst

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,4 +28,9 @@ gitlab.objects module
2828
:show-inheritance:
2929
:exclude-members: Branch, Commit, Content, Event, File, Hook, Issue, Key,
3030
Label, Member, MergeRequest, Milestone, Note, Snippet,
31-
Tag
31+
Tag, canGet, canList, canUpdate, canCreate, canDelete,
32+
requiredUrlAttrs, requiredListAttrs, optionalListAttrs,
33+
optionalGetAttrs, requiredGetAttrs, requiredDeleteAttrs,
34+
requiredCreateAttrs, optionalCreateAttrs,
35+
requiredUpdateAttrs, optionalUpdateAttrs, getRequiresId,
36+
shortPrintAttr, idAttr

‎docs/ext/docstrings.py

Lines changed: 30 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,11 @@
88
fromsphinx.ext.napoleon.docstringimportGoogleDocstring
99

1010

11+
defclassref(value,short=True):
12+
tilde='~'ifshortelse''
13+
return':class:`%sgitlab.objects.%s`'% (tilde,value.__name__)
14+
15+
1116
defsetup(app):
1217
app.connect('autodoc-process-docstring',_process_docstring)
1318
app.connect('autodoc-skip-member',napoleon._skip_member)
@@ -28,58 +33,34 @@ def _process_docstring(app, what, name, obj, options, lines):
2833

2934

3035
classGitlabDocstring(GoogleDocstring):
31-
def_build_doc(self):
32-
cls=self._obj.obj_cls
33-
opt_get_list=cls.optionalGetAttrs
34-
opt_list_list=cls.optionalListAttrs
35-
md_create_list=list(itertools.chain(cls.requiredUrlAttrs,
36-
cls.requiredCreateAttrs))
37-
opt_create_list=cls.optionalCreateAttrs
38-
39-
opt_get_keys="None"
40-
ifopt_get_list:
41-
opt_get_keys=", ".join(['``%s``'%iforiinopt_get_list])
42-
43-
opt_list_keys="None"
44-
ifopt_list_list:
45-
opt_list_keys=", ".join(['``%s``'%iforiinopt_list_list])
46-
47-
md_create_keys=opt_create_keys="None"
48-
ifmd_create_list:
49-
md_create_keys=", ".join(['``%s``'%iforiinmd_create_list])
50-
ifopt_create_list:
51-
opt_create_keys=", ".join(['``%s``'%iforiin
52-
opt_create_list])
53-
54-
md_update_list=list(itertools.chain(cls.requiredUrlAttrs,
55-
cls.requiredUpdateAttrs))
56-
opt_update_list=cls.optionalUpdateAttrs
57-
58-
md_update_keys=opt_update_keys="None"
59-
ifmd_update_list:
60-
md_update_keys=", ".join(['``%s``'%iforiinmd_update_list])
61-
ifopt_update_list:
62-
opt_update_keys=", ".join(['``%s``'%iforiin
63-
opt_update_list])
64-
65-
tmpl_file=os.path.join(os.path.dirname(__file__),'template.j2')
66-
withopen(tmpl_file)asfd:
67-
template=jinja2.Template(fd.read(),trim_blocks=False)
68-
output=template.render(filename=tmpl_file,
69-
cls=cls,
70-
md_create_keys=md_create_keys,
71-
opt_create_keys=opt_create_keys,
72-
md_update_keys=md_update_keys,
73-
opt_update_keys=opt_update_keys,
74-
opt_get_keys=opt_get_keys,
75-
opt_list_keys=opt_list_keys)
36+
_j2_env=None
37+
38+
def_build_j2_env(self):
39+
ifself._j2_envisNone:
40+
self._j2_env=jinja2.Environment(loader=jinja2.FileSystemLoader(
41+
os.path.dirname(__file__)),trim_blocks=False)
42+
self._j2_env.filters['classref']=classref
43+
44+
returnself._j2_env
45+
46+
def_build_manager_doc(self):
47+
env=self._build_j2_env()
48+
template=env.get_template('manager_tmpl.j2')
49+
output=template.render(cls=self._obj.obj_cls)
50+
51+
returnoutput.split('\n')
52+
53+
def_build_object_doc(self):
54+
env=self._build_j2_env()
55+
template=env.get_template('object_tmpl.j2')
56+
output=template.render(obj=self._obj)
7657

7758
returnoutput.split('\n')
7859

7960
def__init__(self,*args,**kwargs):
8061
super(GitlabDocstring,self).__init__(*args,**kwargs)
8162

82-
ifnothasattr(self._obj,'obj_cls')orself._obj.obj_clsisNone:
83-
return
84-
85-
self._parsed_lines=self._build_doc()
63+
ifhasattr(self._obj,'obj_cls')andself._obj.obj_clsisnotNone:
64+
self._parsed_lines=self._build_manager_doc()
65+
elifhasattr(self._obj,'canUpdate')andself._obj.canUpdate:
66+
self._parsed_lines=self._build_object_doc()

‎docs/ext/manager_tmpl.j2

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
Manager for {{ cls | classref() }} objects.
2+
3+
{%ifcls.canUpdate%}
4+
{{ cls | classref() }} objects can be updated.
5+
{%else%}
6+
{{ cls | classref() }} objects **cannot** be updated.
7+
{%endif%}
8+
9+
{%ifcls.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+
{%forkincls.requiredListAttrs%}
17+
* ``{{ k }}`` (required)
18+
{%endfor%}
19+
{%forkincls.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)
27+
{%endif%}
28+
29+
{%ifcls.canGet%}
30+
{%ifcls.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() }}.
38+
{%endif%}
39+
40+
Available keys for ``kwargs`` are:
41+
42+
{%forkincls.requiredGetAttrs%}
43+
* ``{{ k }}`` (required)
44+
{%endfor%}
45+
{%forkincls.optionalGetAttrs%}
46+
* ``{{ k }}`` (optional)
47+
{%endfor%}
48+
* ``sudo`` (string or int): run the request as another user (requires admin
49+
permissions)
50+
{%endif%}
51+
52+
{%ifcls.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+
{%foraincls.requiredUrlAttrs%}
60+
* ``{{ a }}`` (required)
61+
{%endfor%}
62+
{%foraincls.requiredUrlAttrs%}
63+
* ``{{ a }}`` (required if not discovered on the parent objects)
64+
{%endfor%}
65+
{%foraincls.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)
73+
{%endif%}
74+
75+
{%ifcls.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)
84+
{%endif%}

‎docs/ext/object_tmpl.j2

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
.. method:: save(**kwargs)
2+
3+
Send the modified object to the GitLab server. The following attributes are
4+
sent:
5+
6+
{%ifobj.requiredUpdateAttrsorobj.optionalUpdateAttrs%}
7+
{%forainobj.requiredUpdateAttrs%}
8+
* ``{{ a }}`` (required)
9+
{%endfor%}
10+
{%forainobj.optionalUpdateAttrs%}
11+
* ``{{ a }}`` (optional)
12+
{%endfor%}
13+
{%else%}
14+
{%forainobj.requiredCreateAttrs%}
15+
* ``{{ a }}`` (required)
16+
{%endfor%}
17+
{%forainobj.optionalCreateAttrs%}
18+
* ``{{ a }}`` (optional)
19+
{%endfor%}
20+
{%endif%}
21+
22+
Available keys for ``kwargs`` are:
23+
24+
* ``sudo`` (string or int): run the request as another user (requires admin
25+
permissions)

‎docs/ext/template.j2

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

‎test-requirements.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,4 @@ httmock
66
jinja2
77
mock
88
sphinx>=1.3
9+
sphinx_rtd_theme

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp