mirror of
https://github.com/triqs/dft_tools
synced 2024-12-23 04:43:42 +01:00
b5a85e3034
Co-authored-by: Dylan Simon <dylan@dylex.net> Co-authored-by: Alexander Hampel <ahampel@flatironinstitute.org>
137 lines
4.1 KiB
Python
137 lines
4.1 KiB
Python
import re, inspect, textwrap, pydoc
|
|
from docscrape import NumpyDocString, FunctionDoc, ClassDoc
|
|
|
|
class SphinxDocString(NumpyDocString):
|
|
# string conversion routines
|
|
def _str_header(self, name, symbol='`'):
|
|
return ['.. rubric:: ' + name, '']
|
|
|
|
def _str_field_list(self, name):
|
|
return [':' + name + ':']
|
|
|
|
def _str_indent(self, doc, indent=4):
|
|
out = []
|
|
for line in doc:
|
|
out += [' '*indent + line]
|
|
return out
|
|
|
|
def _str_signature(self):
|
|
return ['']
|
|
if self['Signature']:
|
|
return ['``%s``' % self['Signature']] + ['']
|
|
else:
|
|
return ['']
|
|
|
|
def _str_summary(self):
|
|
return self['Summary'] + ['']
|
|
|
|
def _str_extended_summary(self):
|
|
return self['Extended Summary'] + ['']
|
|
|
|
def _str_param_list(self, name):
|
|
out = []
|
|
if self[name]:
|
|
out += self._str_field_list(name)
|
|
out += ['']
|
|
for param,param_type,desc in self[name]:
|
|
out += self._str_indent(['**%s** : %s' % (param.strip(),
|
|
param_type)])
|
|
out += ['']
|
|
out += self._str_indent(desc,8)
|
|
out += ['']
|
|
return out
|
|
|
|
def _str_section(self, name):
|
|
out = []
|
|
if self[name]:
|
|
out += self._str_header(name)
|
|
out += ['']
|
|
content = textwrap.dedent("\n".join(self[name])).split("\n")
|
|
out += content
|
|
out += ['']
|
|
return out
|
|
|
|
def _str_see_also(self, func_role):
|
|
out = []
|
|
if self['See Also']:
|
|
see_also = super(SphinxDocString, self)._str_see_also(func_role)
|
|
out = ['.. seealso::', '']
|
|
out += self._str_indent(see_also[2:])
|
|
return out
|
|
|
|
def _str_warnings(self):
|
|
out = []
|
|
if self['Warnings']:
|
|
out = ['.. warning::', '']
|
|
out += self._str_indent(self['Warnings'])
|
|
return out
|
|
|
|
def _str_index(self):
|
|
idx = self['index']
|
|
out = []
|
|
if len(idx) == 0:
|
|
return out
|
|
|
|
out += ['.. index:: %s' % idx.get('default','')]
|
|
for section, references in idx.items():
|
|
if section == 'default':
|
|
continue
|
|
elif section == 'refguide':
|
|
out += [' single: %s' % (', '.join(references))]
|
|
else:
|
|
out += [' %s: %s' % (section, ','.join(references))]
|
|
return out
|
|
|
|
def _str_references(self):
|
|
out = []
|
|
if self['References']:
|
|
out += self._str_header('References')
|
|
if isinstance(self['References'], str):
|
|
self['References'] = [self['References']]
|
|
out.extend(self['References'])
|
|
out += ['']
|
|
return out
|
|
|
|
def __str__(self, indent=0, func_role="obj"):
|
|
out = []
|
|
out += self._str_signature()
|
|
out += self._str_index() + ['']
|
|
out += self._str_summary()
|
|
out += self._str_extended_summary()
|
|
for param_list in ('Parameters', 'Attributes', 'Methods',
|
|
'Returns','Raises'):
|
|
out += self._str_param_list(param_list)
|
|
out += self._str_warnings()
|
|
out += self._str_see_also(func_role)
|
|
out += self._str_section('Notes')
|
|
out += self._str_references()
|
|
out += self._str_section('Examples')
|
|
out = self._str_indent(out,indent)
|
|
return '\n'.join(out)
|
|
|
|
class SphinxFunctionDoc(SphinxDocString, FunctionDoc):
|
|
pass
|
|
|
|
class SphinxClassDoc(SphinxDocString, ClassDoc):
|
|
pass
|
|
|
|
def get_doc_object(obj, what=None, doc=None):
|
|
if what is None:
|
|
if inspect.isclass(obj):
|
|
what = 'class'
|
|
elif inspect.ismodule(obj):
|
|
what = 'module'
|
|
elif callable(obj):
|
|
what = 'function'
|
|
else:
|
|
what = 'object'
|
|
if what == 'class':
|
|
return SphinxClassDoc(obj, '', func_doc=SphinxFunctionDoc, doc=doc)
|
|
elif what in ('function', 'method'):
|
|
return SphinxFunctionDoc(obj, '', doc=doc)
|
|
else:
|
|
if doc is None:
|
|
doc = pydoc.getdoc(obj)
|
|
return SphinxDocString(doc)
|
|
|