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

Commita2eca72

Browse files
author
Gauvain Pocentek
committed
Automatic doc generation for BaseManager classes
Provide a sphinx extension that parses the required/optioanl attributesand add infoo to the class docstring.
1 parent770dd4b commita2eca72

File tree

5 files changed

+100
-8
lines changed

5 files changed

+100
-8
lines changed

‎docs/conf.py

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -21,15 +21,11 @@
2121
importsphinx
2222

2323
sys.path.append('../')
24+
sys.path.append(os.path.dirname(__file__))
2425
importgitlab
2526

2627
on_rtd=os.environ.get('READTHEDOCS',None)=='True'
2728

28-
ifsphinx.version_info< (1,3,):
29-
napoleon_version="sphinxcontrib.napoleon"
30-
else:
31-
napoleon_version="sphinx.ext.napoleon"
32-
3329
# If extensions (or modules to document with autodoc) are in another directory,
3430
# add these directories to sys.path here. If the directory is relative to the
3531
# documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -44,7 +40,7 @@
4440
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
4541
# ones.
4642
extensions= [
47-
'sphinx.ext.autodoc','sphinx.ext.autosummary',napoleon_version,
43+
'sphinx.ext.autodoc','sphinx.ext.autosummary','ext.docstrings'
4844
]
4945

5046
# Add any paths that contain templates here, relative to this directory.

‎docs/ext/__init__.py

Whitespace-only changes.

‎docs/ext/docstrings.py

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
importitertools
2+
importos
3+
4+
importjinja2
5+
importsix
6+
importsphinx
7+
importsphinx.ext.napoleonasnapoleon
8+
fromsphinx.ext.napoleon.docstringimportGoogleDocstring
9+
10+
11+
defsetup(app):
12+
app.connect('autodoc-process-docstring',_process_docstring)
13+
app.connect('autodoc-skip-member',napoleon._skip_member)
14+
15+
conf=napoleon.Config._config_values
16+
17+
forname, (default,rebuild)insix.iteritems(conf):
18+
app.add_config_value(name,default,rebuild)
19+
return {'version':sphinx.__display_version__,'parallel_read_safe':True}
20+
21+
22+
def_process_docstring(app,what,name,obj,options,lines):
23+
result_lines=lines
24+
docstring=GitlabDocstring(result_lines,app.config,app,what,name,obj,
25+
options)
26+
result_lines=docstring.lines()
27+
lines[:]=result_lines[:]
28+
29+
30+
classGitlabDocstring(GoogleDocstring):
31+
def_build_doc(self):
32+
cls=self._obj.obj_cls
33+
md_create_list=list(itertools.chain(cls.requiredUrlAttrs,
34+
cls.requiredCreateAttrs))
35+
opt_create_list=cls.optionalCreateAttrs
36+
37+
md_create_keys=opt_create_keys="None"
38+
ifmd_create_list:
39+
md_create_keys="%s"%", ".join(['``%s``'%iforiin
40+
md_create_list])
41+
ifopt_create_list:
42+
opt_create_keys="%s"%", ".join(['``%s``'%iforiin
43+
opt_create_list])
44+
45+
md_update_list=list(itertools.chain(cls.requiredUrlAttrs,
46+
cls.requiredUpdateAttrs))
47+
opt_update_list=cls.optionalUpdateAttrs
48+
49+
md_update_keys=opt_update_keys="None"
50+
ifmd_update_list:
51+
md_update_keys="%s"%", ".join(['``%s``'%iforiin
52+
md_update_list])
53+
ifopt_update_list:
54+
opt_update_keys="%s"%", ".join(['``%s``'%iforiin
55+
opt_update_list])
56+
57+
tmpl_file=os.path.join(os.path.dirname(__file__),'template.j2')
58+
withopen(tmpl_file)asfd:
59+
template=jinja2.Template(fd.read(),trim_blocks=False)
60+
output=template.render(filename=tmpl_file,
61+
cls=cls,
62+
md_create_keys=md_create_keys,
63+
opt_create_keys=opt_create_keys,
64+
md_update_keys=md_update_keys,
65+
opt_update_keys=opt_update_keys)
66+
67+
returnoutput.split('\n')
68+
69+
def__init__(self,*args,**kwargs):
70+
super(GitlabDocstring,self).__init__(*args,**kwargs)
71+
72+
ifnothasattr(self._obj,'obj_cls')orself._obj.obj_clsisNone:
73+
return
74+
75+
self._parsed_lines=self._build_doc()

‎docs/ext/template.j2

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
Manager for :class:`gitlab.objects.{{ cls.__name__ }}` objects.
2+
3+
Available actions for this class:
4+
5+
{%ifcls.canList%}- Objects listing{%endif%}
6+
{%ifcls.canGet%}- Unique object retrieval{%endif%}
7+
{%ifcls.canCreate%}- Object creation{%endif%}
8+
{%ifcls.canUpdate%}- Object update{%endif%}
9+
{%ifcls.canDelete%}- Object deletion{%endif%}
10+
11+
{%ifcls.canCreate%}
12+
Mandatory arguments for object creation: {{ md_create_keys }}
13+
14+
Optional arguments for object creation: {{ opt_create_keys }}
15+
{%endif%}
16+
17+
{%ifcls.canUpdate%}
18+
Mandatory arguments for object update: {{ md_create_keys }}
19+
20+
Optional arguments for object update: {{ opt_create_keys }}
21+
{%endif%}

‎test-requirements.txt

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,6 @@ discover
22
testrepository
33
hacking>=0.9.2,<0.10
44
httmock
5+
jinja2
56
mock
6-
sphinx>=1.1.2,!=1.2.0,<1.3
7-
sphinxcontrib-napoleon
7+
sphinx>=1.3

0 commit comments

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