diff options
Diffstat (limited to 'docs/ext/docstrings.py')
| -rw-r--r-- | docs/ext/docstrings.py | 79 |
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() |