def get_doc(self, encoding=None, ignore=1):
"""Overrides ClassDocumenter.get_doc to create the doc scraped from the Process object, then adds additional
content from the class docstring.
"""
from six import text_type
# Get the class docstring. This is a copy of the ClassDocumenter.get_doc method. Using "super" does weird stuff.
docstring = self.get_attr(self.object, '__doc__', None)
# make sure we have Unicode docstrings, then sanitize and split
# into lines
if isinstance(docstring, text_type):
docstring = prepare_docstring(docstring, ignore)
elif isinstance(docstring, str): # this will not trigger on Py3
docstring = prepare_docstring(force_decode(docstring, encoding), ignore)
# Create the docstring by scraping info from the Process instance.
pdocstrings = self.make_numpy_doc()
if self.options.docstring and docstring is not None:
# Add the sections from the class docstring itself.
pdocstrings.extend(docstring[self.options.skiplines:])
# Parse using the Numpy docstring format.
docstrings = NumpyDocstring(pdocstrings, self.env.config, self.env.app, what='class', obj=self.object,
options=self.options)
return [docstrings.lines()]
def make_rst(self):
module_name, class_name = self.arguments[:2]
obj = import_object(module_name, class_name)
events = [(event._func.__name__, opcode, format_args(event._func), prepare_docstring(event._func.__doc__)) for opcode, event in enumerate(obj.events)]
reqs = [(req._func.__name__, opcode, format_args(req._func), prepare_docstring(req._func.__doc__)) for opcode, req in enumerate(obj.requests)]
context = {
'module': module_name,
'class_name': class_name,
'obj': obj,
'events': events,
'requests': reqs
}
rst = wl_protocol_template.render(**context)
for line in rst.splitlines():
yield line
def make_rst(self, section_title_set):
# print('importing falcon app %s...' % self.arguments[0])
app = autohttp_import_object(self.arguments[0])
for method, path, handler in get_routes(app):
docstring = handler.__doc__
if not isinstance(docstring, str):
analyzer = ModuleAnalyzer.for_module(handler.__module__)
docstring = force_decode(docstring, analyzer.encoding)
if not docstring and 'include-empty-docstring' not in self.options:
continue
if not docstring:
continue
docstring = prepare_docstring(docstring)
# generate section title if needed
if path.startswith('/api'):
section_title = '/'.join(path.split('/')[0:4])
else:
section_title = path
if section_title not in section_title_set:
section_title_set.add(section_title)
yield section_title
yield '_' * len(section_title)
for line in autohttp_http_directive(method, path, docstring):
yield line
def make_rst(self):
app = autohttp.import_object(self.arguments[0])
for method, path, endpoint in get_routes(app):
try:
blueprint, endpoint_internal = endpoint.split('.')
if blueprint in self.undoc_blueprints:
continue
except ValueError:
pass # endpoint is not within a blueprint
if self.endpoints and endpoint not in self.endpoints:
continue
if endpoint in self.undoc_endpoints:
continue
try:
static_url_path = app.static_url_path # Flask 0.7 or higher
except AttributeError:
static_url_path = app.static_path # Flask 0.6 or under
if ('undoc-static' in self.options and endpoint == 'static'
and path == static_url_path + '/(path:filename)'):
continue
view = app.view_functions[endpoint]
docstring = view.__doc__ or ''
if not isinstance(docstring, unicode):
analyzer = ModuleAnalyzer.for_module(view.__module__)
docstring = force_decode(docstring, analyzer.encoding)
if not docstring and 'include-empty-docstring' not in self.options:
continue
docstring = prepare_docstring(docstring)
for line in autohttp.http_directive(method, path, docstring):
yield line
def make_rst(self, section_title_set):
# print('importing falcon app %s...' % self.arguments[0])
app = autohttp_import_object(self.arguments[0])
for method, path, handler in get_routes(app):
docstring = handler.__doc__
if not isinstance(docstring, unicode):
analyzer = ModuleAnalyzer.for_module(handler.__module__)
docstring = force_decode(docstring, analyzer.encoding)
if not docstring and 'include-empty-docstring' not in self.options:
continue
if not docstring:
continue
if not (handler.__self__.allow_read_no_auth and method == 'GET'):
docstring += '\n:reqheader Authorization: see :ref:`hmac-auth-label`.\n'
docstring = prepare_docstring(docstring)
# generate section title if needed
if path.startswith('/v'):
section_title = '/'.join(path.split('/')[0:3])
else:
section_title = path
if section_title not in section_title_set:
section_title_set.add(section_title)
yield section_title
yield '_' * len(section_title)
for line in autohttp_http_directive(method, path, docstring):
yield line
def get_doc(self, encoding=None):
content = self.env.config.autoclass_content
docstrings = []
docstring = self.get_attr(self.object, '__doc__', None)
if docstring:
docstrings.append(docstring)
# for classes, what the "docstring" is can be controlled via a
# config value; the default is only the class docstring
if content in ('both', 'init'):
constructor = self.get_constructor()
if constructor:
initdocstring = self.get_attr(constructor, '__doc__', None)
else:
initdocstring = None
if initdocstring:
if content == 'init':
docstrings = [initdocstring]
else:
docstrings.append(initdocstring)
return [
prepare_docstring(force_decode(docstring, encoding))
for docstring in docstrings
]
def function_reference(f, attr, args, doc):
lines = []
lines.extend([f, "-" * len(f), ""])
docstring = prepare_docstring(doc)
lines.extend([docstring[0], ""])
arg_types = []
for t in args:
if isinstance(t, list):
inner_types = [t2.__name__ for t2 in t]
arg_types.append(" | ".join(inner_types))
continue
arg_types.append(t.__name__)
arg_s = "(%s)" % ", ".join(arg_types)
lines.extend([":Arguments: %s" % arg_s, ""])
lines.extend(docstring[1:])
lines.append("")
return lines
def description(f):
if f.__doc__ == None:
return ''
try:
return next(iter(prepare_docstring(f.__doc__)))
except StopIteration:
return ''
def docs(f):
if f.__doc__ == None:
raise StopIteration
for line in prepare_docstring(f.__doc__):
m = re.match(r'^:param (?:[^:]+ )([^:]+): (.+)$', line)
if m:
yield m.groups()
def make_rst(self):
app = import_object(self.arguments[0])
if self.endpoints:
routes = itertools.chain(
*[get_routes(app, endpoint) for endpoint in self.endpoints])
else:
routes = get_routes(app)
# sort by path then method
for method, paths, endpoint in sorted(routes,
key=operator.itemgetter(1, 0)):
if endpoint in self.undoc_endpoints:
continue
view = app._endpoints[endpoint]
docstring = view.__doc__ or ''
if hasattr(view, 'view_class'):
meth_func = getattr(view.view_class, method.lower(), None)
if meth_func and meth_func.__doc__:
docstring = meth_func.__doc__
if not isinstance(docstring, six.text_type):
analyzer = ModuleAnalyzer.for_module(view.__module__)
docstring = force_decode(docstring, analyzer.encoding)
if not docstring and 'include-empty-docstring' not in self.options:
continue
docstring = self.fix_docstring(docstring)
docstring = prepare_docstring(docstring)
for line in http_directive(method, paths, docstring):
yield line
def make_rst(self):
app = import_object(self.arguments[0])
for method, path, endpoint in get_routes(app):
try:
blueprint, endpoint_internal = endpoint.split('.')
if blueprint in self.undoc_blueprints:
continue
except ValueError:
pass # endpoint is not within a blueprint
if self.endpoints and endpoint not in self.endpoints:
continue
if endpoint in self.undoc_endpoints:
continue
try:
static_url_path = app.static_url_path # Flask 0.7 or higher
except AttributeError:
static_url_path = app.static_path # Flask 0.6 or under
if ('undoc-static' in self.options and endpoint == 'static' and
path == static_url_path + '/(path:filename)'):
continue
view = app.view_functions[endpoint]
docstring = view.__doc__ or ''
if hasattr(view, 'view_class'):
meth_func = getattr(view.view_class, method.lower(), None)
if meth_func and meth_func.__doc__:
docstring = meth_func.__doc__
if not isinstance(docstring, unicode):
analyzer = ModuleAnalyzer.for_module(view.__module__)
docstring = force_decode(docstring, analyzer.encoding)
if not docstring and 'include-empty-docstring' not in self.options:
continue
docstring = prepare_docstring(docstring)
for line in http_directive(method, path, docstring):
yield line
def get_doc(self, encoding=None, ignore: int = 1) -> List[List[str]]:
"""Decode and return lines of the docstring(s) for the object."""
# If the current object is a Column (or InstrumentedAttribute) and
# it appears to have metadata...
if (isinstance(self.object, (Column, InstrumentedAttribute))
and hasattr(self.object, COLUMN_META_ATTR)):
# Get the metadata from the column.
meta = self.object.__meta__
# Create an image that we can put in-line with the rest of the
# docstring.
img_sub = str(uuid.uuid4()).replace('-', '')
lines = [
f".. |{img_sub}| image:: {IMAGES_PATH / 'column.svg'}",
' :width: 24px', ' :height: 24px', '',
f"|{img_sub}| **{meta.label}**", '', meta.description, '',
self.doc_enum_table(enum_cls=Usage,
meta=meta,
excluded={Usage.NONE}), '',
self.doc_enum_table(enum_cls=Requirement,
meta=meta,
excluded={Requirement.NONE}), ''
]
# If the meta-data indicates there is a related NENA field...
if meta.nena is not None:
# ...we'll include it!
lines.extend([f':NENA: *{meta.nena}*', ''])
# Put it all together.
rst = '\n'.join(lines)
# OK, ship it out!
return [prepare_docstring(rst, 0)] # don't ignore it!
else: # In all other cases, let the parent class do its thing.
return super().get_doc(encoding=encoding, ignore=ignore)
def make_rst_for_method(self, path, method, http_method):
docstring = prepare_docstring((method.__doc__ or '').rstrip('\n'))
blank_line = docstring[-1]
docstring = docstring[:-1] # remove blank line appended automatically
funcdef = method._wsme_definition
# Add the parameter type information. Assumes that the
# developer has provided descriptions of the parameters.
for arg in funcdef.arguments:
docstring.append(':type %s: %s' %
(arg.name, datatypename(arg.datatype)))
# Add a blank line before return type to avoid the formatting issues
# that are caused because of missing blank lines between blocks
docstring.append(blank_line)
# Add the return type
if funcdef.return_type:
return_type = datatypename(funcdef.return_type)
docstring.append(':return type: %s' % return_type)
# restore the blank line added as a spacer
docstring.append(blank_line)
directive = http_directive(http_method, path, docstring)
return directive
def add_content(self, more_content, no_docstring=False):
if not is_mpd_running():
return
try:
cls = self.object
instance = cls(must_start_worker = False, must_handle_state = False)
try:
#instance.initialize_code()
parameter_documentation = self.get_sphinx_doc_for_parameters(instance.parameters)
finally:
instance.stop()
except Exception as ex:
print ex
return
if self.analyzer:
# prevent encoding errors when the file name is non-ASCII
filename = unicode(self.analyzer.srcname,
sys.getfilesystemencoding(), 'replace')
sourcename = u'%s:docstring of %s' % (filename, self.fullname)
else:
sourcename = u'docstring of %s' % self.fullname
encoding = self.analyzer and self.analyzer.encoding
lines = prepare_docstring(force_decode(parameter_documentation, encoding))
for i, line in enumerate(self.process_doc([lines,])):
self.add_line(line, sourcename, i)
def get_doc(self, encoding=None, ignore=1):
content = self.env.config.autoclass_content
docstrings = []
attrdocstring = self.get_attr(self.object, 'doc', None)
if attrdocstring:
docstrings.append(attrdocstring)
# for classes, what the "docstring" is can be controlled via a
# config value; the default is only the class docstring
if content in ('both', 'init'):
initdocstring = self.get_attr(
self.get_attr(self.object, '__init__', None), '__doc__')
# for new-style classes, no __init__ means default __init__
if initdocstring == object.__init__.__doc__:
initdocstring = None
if initdocstring:
if content == 'init':
docstrings = [initdocstring]
else:
docstrings.append(initdocstring)
doc = []
for docstring in docstrings:
if not isinstance(docstring, unicode):
docstring = force_decode(docstring, encoding)
doc.append(prepare_docstring(docstring))
return doc
def variable_reference(v, st_type, in_type, default, doc, tier):
lines = [
v,
'-' * len(v),
'',
]
docstring = prepare_docstring(doc)
lines.extend([
docstring[0],
'',
])
lines.extend([
':Storage Type: ``%s``' % st_type.__name__,
':Input Type: ``%s``' % in_type.__name__,
':Default Value: %s' % default,
'',
])
lines.extend(docstring[1:])
lines.append('')
return lines
def get_doc(self, encoding=None):
content = self.env.config.autoclass_content
docstrings = []
attrdocstring = sage_getdoc_original(self.object)
if attrdocstring:
docstrings.append(attrdocstring)
# for classes, what the "docstring" is can be controlled via a
# config value; the default is only the class docstring
if content in ('both', 'init'):
initdocstring = sage_getdoc_original(
self.get_attr(self.object, '__init__', None))
# for new-style classes, no __init__ means default __init__
if initdocstring == object.__init__.__doc__:
initdocstring = None
if initdocstring:
if content == 'init':
docstrings = [initdocstring]
else:
docstrings.append(initdocstring)
doc = []
for docstring in docstrings:
if not isinstance(docstring, unicode):
docstring = force_decode(docstring, encoding)
doc.append(prepare_docstring(docstring))
return doc
def make_rst(self, qref=False):
app = import_object(self.arguments[0])
if self.endpoints:
routes = itertools.chain(*[
get_routes(app, endpoint, self.order)
for endpoint in self.endpoints
])
else:
routes = get_routes(app, order=self.order)
for method, paths, endpoint in routes:
try:
blueprint, _, endpoint_internal = endpoint.rpartition('.')
if self.blueprints and blueprint not in self.blueprints:
continue
if blueprint in self.undoc_blueprints:
continue
except ValueError:
pass # endpoint is not within a blueprint
if endpoint in self.undoc_endpoints:
continue
try:
static_url_path = app.static_url_path # Flask 0.7 or higher
except AttributeError:
static_url_path = app.static_path # Flask 0.6 or under
if ('undoc-static' in self.options and endpoint == 'static'
and static_url_path + '/(path:filename)' in paths):
continue
view = app.view_functions[endpoint]
if self.modules and view.__module__ not in self.modules:
continue
if self.undoc_modules and view.__module__ in self.modules:
continue
docstring = view.__doc__ or ''
if hasattr(view, 'view_class'):
meth_func = getattr(view.view_class, method.lower(), None)
if meth_func and meth_func.__doc__:
docstring = meth_func.__doc__
if not isinstance(docstring, six.text_type):
analyzer = ModuleAnalyzer.for_module(view.__module__)
docstring = force_decode(docstring, analyzer.encoding)
if not docstring and 'include-empty-docstring' not in self.options:
continue
docstring = prepare_docstring(docstring)
if qref == True:
for path in paths:
row = quickref_directive(method, path, docstring)
yield row
else:
lines = list(http_directive(method, paths, docstring))
self.state.document.settings.env.app.emit(
'autodoc-process-docstring', 'function', None, view, {},
lines)
for line in lines:
yield line
def _get_doc(reference: IReference) -> Optional[List[List[str]]]:
"""Return the docstring of an IReference type (e.g. Namespace or Var)."""
docstring = reference.meta and reference.meta.val_at(_DOC_KW)
if docstring is None:
return None
assert isinstance(docstring, str)
return [prepare_docstring(docstring)]
def fill_in_result(object_schema):
result["properties"] = {}
for property, propSchema in object_schema[u"properties"].iteritems():
attr = result["properties"][property] = {}
attr["title"] = propSchema["title"]
attr["description"] = prepare_docstring(propSchema["description"])
attr["required"] = property in object_schema.get("required", [])
attr["type"] = propSchema["type"]
def _rest2node(self, rest, container=None):
vl = ViewList(prepare_docstring(rest))
if container is None:
node = nodes.container()
else:
node = container()
nested_parse_with_titles(self.state, vl, node)
return node
def get_doc(self, encoding=None):
"""Decode and return lines of the docstring(s) for the object."""
docstring = self.get_attr(self.object, '__doc__', None)
if docstring:
# make sure we have Unicode docstrings, then sanitize and split
# into lines
return [prepare_docstring(force_decode(docstring, encoding))]
return []
def _rest2node(self, rest, container=None):
vl = ViewList(prepare_docstring(rest))
if container is None:
node = nodes.container()
else:
node = container()
nested_parse_with_titles(self.state, vl, node)
return node
def fill_in_result(object_schema):
result['properties'] = {}
for prop, propSchema in object_schema[u'properties'].iteritems():
attr = result['properties'][prop] = {}
attr['title'] = propSchema['title']
attr['description'] = prepare_docstring(propSchema['description'])
attr['required'] = prop in object_schema.get("required", [])
attr['type'] = propSchema['type']
def get_doc(self, encoding=None):
"""Decode and return lines of the docstring(s) for the object."""
docstring = self.get_attr(self.object, '__doc__', None)
if docstring:
# make sure we have Unicode docstrings, then sanitize and split
# into lines
return [prepare_docstring(force_decode(docstring, encoding))]
return []
def generate_docs(self, clspath, more_content):
"""Generate documentation for this configman class"""
obj = import_class(clspath)
sourcename = 'docstring of %s' % clspath
# Add the header
modname, clsname = split_clspath(clspath)
self.add_line('.. %s:%s:: %s.%s' % ('py', 'class', modname, clsname), sourcename)
self.add_line('', sourcename)
# Add the docstring if there is one
docstring = getattr(obj, '__doc__', None)
if docstring:
docstringlines = prepare_docstring(docstring, ignore=1)
for i, line in enumerate(docstringlines):
self.add_line(' ' + line, sourcename, i)
self.add_line('', '')
# Add additional content from the directive if there was any
if more_content:
for line, src in zip(more_content.data, more_content.items):
self.add_line(' ' + line, src[0], src[1])
self.add_line('', '')
# Add configman related content
namespace = Namespace()
for cls in reversed(obj.__mro__):
try:
namespace.update(cls.required_config)
except AttributeError:
pass
if namespace:
self.add_line(' Configuration:', '')
self.add_line('', '')
sourcename = 'class definition'
def generate_namespace_docs(namespace, basename=''):
for name, value in namespace.iteritems():
if isinstance(value, Namespace):
generate_namespace_docs(value, name + '_')
elif isinstance(value, Option):
self.add_line(' ``%s``' % (basename + value.name), sourcename)
self.add_line(' :default: ``%r``' % value.default, sourcename)
self.add_line(' :converter: %r' % value.from_string_converter, sourcename)
if value.reference_value_from:
self.add_line(' :base: ``%s``' % (value.reference_value_from + '.' + value.name), sourcename)
self.add_line('', '')
self.add_line(' %s' % value.doc, sourcename)
self.add_line('', '')
elif isinstance(value, Aggregation):
# Ignore aggregations--they're for setting something up
# using a bunch of configuratino things (I think)
pass
else:
raise Exception('No idea what to do with %r' % value)
generate_namespace_docs(namespace)
def add_docstring(docstring):
if docstring:
with IndentBlock(self):
self.add_line(u'', directive_name)
source_name = u'docstring of %s.%s' % (self.fullname, name)
docstring = [prepare_docstring(force_decode(docstring, None))]
for i, line in enumerate(self.process_doc(docstring)):
self.add_line(line, source_name, i)
self.add_line(u'', directive_name)
def _introspectRoute(route, exampleByIdentifier, schema_store):
"""
Given a L{KleinRoute}, extract the information to generate documentation.
@param route: Route to inspect
@type route: L{KleinRoute}
@param exampleByIdentifier: A one-argument callable that accepts an example
identifier and returns an HTTP session example.
@param dict schema_store: A mapping between schema paths
(e.g. ``b/v1/types.json``) and the JSON schema structure.
@return: Information about the route
@rtype: L{dict} with the following keys.
- C{'description'}:
L{list} of L{str} containing a prose description of the endpoint.
- C{'input'} I{(optional)}:
L{dict} describing the input schema. Has C{'properties'} key with
a L{list} of L{dict} of L{dict} with keys C{'title'},
C{'description'} and C{'required'} describing the toplevel
properties of the schema.
- C{'input_schema'} I{(optional)}:
L{dict} including the verbatim input JSON Schema.
- C{'output'} I{(optional)}:
see C{'input'}.
- C{'output_schema'} I{(optional)}:
L{dict} including the verbatim output JSON Schema.
- C{'paged'} I{(optional)}:
If present, the endpoint is paged.
L{dict} with keys C{'defaultKey'} and C{'otherKeys'} giving the
names of default and available sort keys.
- C{'examples'}:
A list of examples (L{Example} instances) for this endpoint.
"""
result = {}
userDocumentation = route.attributes.get("userDocumentation",
"Undocumented.")
result['description'] = prepare_docstring(userDocumentation)
inputSchema = route.attributes.get('inputSchema', None)
outputSchema = route.attributes.get('outputSchema', None)
if inputSchema:
result['input'] = _parseSchema(inputSchema, schema_store)
result["input_schema"] = inputSchema
if outputSchema:
result['output'] = _parseSchema(outputSchema, schema_store)
result["output_schema"] = outputSchema
examples = route.attributes.get("examples") or []
result['examples'] = list(
Example.fromDictionary(exampleByIdentifier(identifier))
for identifier in examples)
return result
def fill_in_result(object_schema):
result['properties'] = {}
for property, propSchema in object_schema[u'properties'].iteritems():
attr = result['properties'][property] = {}
attr['title'] = propSchema['title']
attr['description'] = prepare_docstring(
propSchema['description'])
attr['required'] = property in object_schema.get("required", [])
attr['type'] = propSchema['type']
def _introspectRoute(route, exampleByIdentifier, schema_store):
"""
Given a L{KleinRoute}, extract the information to generate documentation.
@param route: Route to inspect
@type route: L{KleinRoute}
@param exampleByIdentifier: A one-argument callable that accepts an example
identifier and returns an HTTP session example.
@param dict schema_store: A mapping between schema paths
(e.g. ``b/v1/types.json``) and the JSON schema structure.
@return: Information about the route
@rtype: L{dict} with the following keys.
- C{'description'}:
L{list} of L{str} containing a prose description of the endpoint.
- C{'input'} I{(optional)}:
L{dict} describing the input schema. Has C{'properties'} key with
a L{list} of L{dict} of L{dict} with keys C{'title'},
C{'description'} and C{'required'} describing the toplevel
properties of the schema.
- C{'input_schema'} I{(optional)}:
L{dict} including the verbatim input JSON Schema.
- C{'output'} I{(optional)}:
see C{'input'}.
- C{'output_schema'} I{(optional)}:
L{dict} including the verbatim output JSON Schema.
- C{'paged'} I{(optional)}:
If present, the endpoint is paged.
L{dict} with keys C{'defaultKey'} and C{'otherKeys'} giving the
names of default and available sort keys.
- C{'examples'}:
A list of examples (L{Example} instances) for this endpoint.
"""
result = {}
userDocumentation = route.attributes.get(
"userDocumentation", "Undocumented.")
result['description'] = prepare_docstring(userDocumentation)
inputSchema = route.attributes.get('inputSchema', None)
outputSchema = route.attributes.get('outputSchema', None)
if inputSchema:
result['input'] = _parseSchema(inputSchema, schema_store)
result["input_schema"] = inputSchema
if outputSchema:
result['output'] = _parseSchema(outputSchema, schema_store)
result["output_schema"] = outputSchema
examples = route.attributes.get("examples") or []
result['examples'] = list(
Example.fromDictionary(exampleByIdentifier(identifier))
for identifier in examples)
return result
def _rst2node(self, body: str) -> docutils.nodes.paragraph:
"""Process an ReSTructuredTect block and return a paragraph containing it.
Used, primarily, to process docstrings.
"""
node = nodes.paragraph()
result = ViewList(prepare_docstring(body))
self.state.nested_parse(result, 0, node)
return node
def test_prepare_docstring():
docstring = """multiline docstring
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna
aliqua::
Ut enim ad minim veniam, quis nostrud exercitation
ullamco laboris nisi ut aliquip ex ea commodo consequat.
"""
assert (prepare_docstring(docstring) ==
["multiline docstring",
"",
"Lorem ipsum dolor sit amet, consectetur adipiscing elit,",
"sed do eiusmod tempor incididunt ut labore et dolore magna",
"aliqua::",
"",
" Ut enim ad minim veniam, quis nostrud exercitation",
" ullamco laboris nisi ut aliquip ex ea commodo consequat.",
""])
assert (prepare_docstring(docstring, 5) ==
["multiline docstring",
"",
"Lorem ipsum dolor sit amet, consectetur adipiscing elit,",
"sed do eiusmod tempor incididunt ut labore et dolore magna",
"aliqua::",
"",
"Ut enim ad minim veniam, quis nostrud exercitation",
" ullamco laboris nisi ut aliquip ex ea commodo consequat.",
""])
docstring = """
multiline docstring with leading empty lines
"""
assert (prepare_docstring(docstring) ==
["multiline docstring with leading empty lines",
""])
docstring = "single line docstring"
assert (prepare_docstring(docstring) ==
["single line docstring",
""])
def test_prepare_docstring():
docstring = """multiline docstring
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna
aliqua::
Ut enim ad minim veniam, quis nostrud exercitation
ullamco laboris nisi ut aliquip ex ea commodo consequat.
"""
assert (prepare_docstring(docstring) ==
["multiline docstring",
"",
"Lorem ipsum dolor sit amet, consectetur adipiscing elit,",
"sed do eiusmod tempor incididunt ut labore et dolore magna",
"aliqua::",
"",
" Ut enim ad minim veniam, quis nostrud exercitation",
" ullamco laboris nisi ut aliquip ex ea commodo consequat.",
""])
assert (prepare_docstring(docstring, 5) ==
["multiline docstring",
"",
"Lorem ipsum dolor sit amet, consectetur adipiscing elit,",
"sed do eiusmod tempor incididunt ut labore et dolore magna",
"aliqua::",
"",
"Ut enim ad minim veniam, quis nostrud exercitation",
" ullamco laboris nisi ut aliquip ex ea commodo consequat.",
""])
docstring = """
multiline docstring with leading empty lines
"""
assert (prepare_docstring(docstring) ==
["multiline docstring with leading empty lines",
""])
docstring = "single line docstring"
assert (prepare_docstring(docstring) ==
["single line docstring",
""])
def document_members(self, all_members=True):
oldindent = self.indent
members = list(self.object.attributes.items())
if self.options.members is not autodoc.ALL:
specified = []
for line in (self.options.members or []):
specified.extend(line.split())
members = {
name: value for name, value in members if name in specified
}
member_order = (
self.options.member_order or self.env.config.autodoc_member_order
)
if member_order == 'alphabetical':
members.sort()
if member_order == 'groupwise':
members.sort(key=lambda e: isinstance(e[1], Method))
elif member_order == 'bysource' and self.analyzer:
name = self.object.__name__
def keyfunc(entry):
return self.analyzer.tagorder.get(
'.'.join((name, entry[0])),
len(self.analyzer.tagorder)
)
members.sort(key=keyfunc)
for name, specification in members:
self.add_line(u'', '<autointerface>')
if isinstance(specification, Method):
self.add_line(
u'.. method:: {name}{arguments}'.format(
name=name,
arguments=inspect.formatargspec(
*specification.argument_specification
)
),
'<autointerface>'
)
else:
self.add_line(
u'.. attribute:: {name}'.format(name=name),
'<autointerface>'
)
doc = specification.docstring
if doc:
self.add_line(u'', '<autointerface>')
self.indent += self.content_indent
sourcename = u'docstring of %s.%s' % (self.fullname, name)
docstrings = [prepare_docstring(force_decode(doc, None))]
for i, line in enumerate(self.process_doc(docstrings)):
self.add_line(line, sourcename, i)
self.add_line(u'', '<autointerface>')
self.indent = oldindent
def parse_docstring(docstring, flag=False):
"""Parse the docstring into its components.
:returns: a dictionary of form
{
"short_description": ...,
"long_description": ...,
"params": [{"name": ..., "doc": ...}, ...],
"returns": ...
}
"""
short_description = long_description = returns = ""
params = []
if docstring:
docstring = "\n".join(docstrings.prepare_docstring(docstring))
lines = docstring.split("\n", 1)
short_description = lines[0]
if len(lines) > 1:
reminder = lines[1].strip()
params_returns_desc = None
match_parameters = PARAMETERS_REGEX.search(reminder)
if match_parameters:
long_desc_end = match_parameters.start()
long_description = pypandoc.convert_text(
reminder[:long_desc_end].rstrip(), 'md', format='rst')
reminder = reminder[long_desc_end:].strip()
else:
long_description = pypandoc.convert_text(reminder.rstrip(),
'md',
format='rst')
match = OTHER_PARAMETER_REGEX.search(reminder)
if match:
end = match.start()
if not match_parameters:
long_description = pypandoc.convert_text(
reminder[:end].rstrip(), 'md', format='rst')
reminder = reminder[end:].strip()
if reminder:
params = {}
for name, tpe, doc in PARAMETER_REGEX.findall(reminder):
params[name] = (tpe, doc)
return {
"short_description": short_description,
"long_description": long_description,
"params": params,
}
def get_doc(self, encoding: str = None, ignore: int = 1) -> List[List[str]]:
if(getattr(self.parent, '__attrdoc__', None) is not None):
docs = {n:v for k in self.parent.__attrdoc__.split('#:') for n,v in [k.split('\n', 1)]}
name = self.fullname.split('.')[-1]
if(name in docs):
return [prepare_docstring(docs[name])]
else:
return []
else:
return []
def _rest2node(self, rest, container=None):
""" creates a docutils node from some rest-markup
"""
vl = ViewList(prepare_docstring(rest))
if container is None:
node = nodes.container()
else:
node = container()
nested_parse_with_titles(self.state, vl, node)
return node
def format_docstring(docstring):
"""Format the docstring to make it well-readable.
:param docstring: string.
:returns: formatted string.
"""
if docstring:
return "\n".join(docstrings.prepare_docstring(docstring))
else:
return ""
def add_signal(self, signal):
self.add_line(f".. dbus:signal:: {signal.name}")
self.add_line("")
self.indent += " "
for arg in signal.args:
self.add_line(f":arg {arg.signature} {arg.name}: {arg.doc_string}")
self.add_line("")
for line in prepare_docstring("\n" + signal.doc_string):
self.add_line(line)
self.indent = self.indent[:-3]
def format_docstring(docstring):
"""Format the docstring to make it well-readable.
:param docstring: string.
:returns: formatted string.
"""
if docstring:
return "\n".join(docstrings.prepare_docstring(docstring))
else:
return ""
def generate(self, **kwargs):
self.parse_name()
self.real_modname = self.modname
self.add_directive_header(u'')
first_node = self.ast_node[0]
if first_node.tag == 'Comment':
for line in prepare_docstring(first_node['comment']):
self.add_line(line, self.name)
self.document_members(True)
def make_rst(self):
module_name, class_name = self.arguments[:2]
obj = import_object(module_name, class_name)
events = [(event.py_func.__name__, opcode, format_args(event.py_func),
prepare_docstring(event.py_func.__doc__))
for opcode, event in enumerate(obj.events)]
reqs = [(req.py_func.__name__, opcode, format_args(req.py_func),
prepare_docstring(req.py_func.__doc__))
for opcode, req in enumerate(obj.requests)]
context = {
'module': module_name,
'class_name': class_name,
'obj': obj,
'events': events,
'requests': reqs
}
rst = wl_protocol_template.render(**context)
for line in rst.splitlines():
yield line
def run(self):
drv_name = self.arguments[0]
driver = registry.get_driver(drv_name)
types = ', '.join(class_.__name__ for class_ in driver.__bases__)
doc = '\n'.join(docstrings.prepare_docstring(driver.__doc__))
subcat = utils.subcategory('{} [{}]'.format(drv_name, types))
subcat.extend(utils.parse_text(doc))
return [subcat]
def generate(self, **kwargs):
self.parse_name()
self.real_modname = self.modname
self.add_directive_header(u'')
first_node = self.ast_node[0]
if first_node.tag == 'Comment':
for line in prepare_docstring(first_node['comment']):
self.add_line(line, self.name)
self.document_members(True)
def get_doc(self, encoding=None, ignore=1):
"""This patch prevents autodata object instances from having the docstrings of their classes"""
docstring = getdoc(self.object, self.get_attr,
self.env.config.autodoc_inherit_docstrings)
obj_type_doc = getattr(type(self.object), '__doc__', None)
if docstring == obj_type_doc:
docstring = None
if docstring:
tab_width = self.directive.state.document.settings.tab_width
return [prepare_docstring(docstring, ignore, tab_width)]
return []
def make_rst(self):
env = self.state.document.settings.env
path = self.arguments[0]
docstring = parse_jinja_comment(
os.path.join(env.config['jinja_template_path'], path))
docstring = prepare_docstring(docstring)
if env.config['jinja_template_path']:
for line in jinja_directive(path, docstring):
yield line
yield ''
def make_rst(self):
env = self.state.document.settings.env
path = self.arguments[0]
docstring=parse_jinja_comment(
os.path.join(env.config['jinja_template_path'],path))
docstring = prepare_docstring(docstring)
if env.config['jinja_template_path']:
for line in jinja_directive(path, docstring):
yield line
yield ''
def special_reference(v, func, typ, doc):
lines = [v, "-" * len(v), ""]
docstring = prepare_docstring(doc)
lines.extend([docstring[0], "", ":Type: ``%s``" % typ.__name__, ""])
lines.extend(docstring[1:])
lines.append("")
return lines
def _prepare_docstring(self, docstring):
"""
Remove anything that appears after a line that starts with ":". This
makes it possible to remove directives like ":param XXX:" which are
intended for Langkit developpers, not for users.
"""
result = prepare_docstring(docstring)
for i, line in enumerate(result):
if line.startswith(':'):
return '\n'.join(result[:i]).rstrip().split('\n')
return result
def make_rst(self, qref=False):
app = import_object(self.arguments[0])
if self.endpoints:
routes = itertools.chain(*[get_routes(app, endpoint, self.order)
for endpoint in self.endpoints])
else:
routes = get_routes(app, order=self.order)
for method, paths, endpoint in routes:
try:
blueprint, _, endpoint_internal = endpoint.rpartition('.')
if self.blueprints and blueprint not in self.blueprints:
continue
if blueprint in self.undoc_blueprints:
continue
except ValueError:
pass # endpoint is not within a blueprint
if endpoint in self.undoc_endpoints:
continue
try:
static_url_path = app.static_url_path # Flask 0.7 or higher
except AttributeError:
static_url_path = app.static_path # Flask 0.6 or under
if ('undoc-static' in self.options and endpoint == 'static' and
static_url_path + '/(path:filename)' in paths):
continue
view = app.view_functions[endpoint]
if self.modules and view.__module__ not in self.modules:
continue
if self.undoc_modules and view.__module__ in self.modules:
continue
docstring = view.__doc__ or ''
if hasattr(view, 'view_class'):
meth_func = getattr(view.view_class, method.lower(), None)
if meth_func and meth_func.__doc__:
docstring = meth_func.__doc__
if not isinstance(docstring, six.text_type):
analyzer = ModuleAnalyzer.for_module(view.__module__)
docstring = force_decode(docstring, analyzer.encoding)
if not docstring and 'include-empty-docstring' not in self.options:
continue
docstring = prepare_docstring(docstring)
if qref == True:
for path in paths:
row = quickref_directive(method, path, docstring)
yield row
else:
for line in http_directive(method, paths, docstring):
yield line
def get_doc(self, encoding=None, ignore=1):
lines = getattr(self, '_new_docstrings', None)
if lines is not None:
return lines
doc = super(AnyBlokMethodDocumenter, self).get_doc(encoding=encoding,
ignore=ignore)
autodocs = self.get_attr(self.object, 'autodocs', [])
for autodoc in autodocs:
doc.append(prepare_docstring(autodoc, ignore))
return doc
def add_method(self, method):
self.add_line(f".. dbus:method:: {method.name}")
self.add_line("")
self.indent += " "
for arg in method.in_args:
self.add_line(f":arg {arg.signature} {arg.name}: {arg.doc_string}")
for arg in method.out_args:
self.add_line(f":ret {arg.signature} {arg.name}: {arg.doc_string}")
self.add_line("")
for line in prepare_docstring("\n" + method.doc_string):
self.add_line(line)
self.indent = self.indent[:-3]
def get_doc(self, encoding=None, ignore=1):
lines = getattr(self, '_new_docstrings', None)
if lines is not None:
return lines
doc = super(AnyBlokMethodDocumenter, self).get_doc(encoding=encoding,
ignore=ignore)
autodocs = self.get_attr(self.object, 'autodocs', [])
for autodoc in autodocs:
doc.append(prepare_docstring(autodoc, ignore))
return doc
def run(self):
drv_name = self.arguments[0]
driver = registry.get_driver(drv_name)
types = ', '.join(class_.__name__ for class_ in driver.__bases__)
services = sorted(driver.list_supported_services())
doc = '\n'.join(docstrings.prepare_docstring(driver.__doc__))
subcat = utils.subcategory('{} [{}]'.format(drv_name, types))
subcat.extend(utils.parse_text(doc))
subcat.extend(utils.parse_text('**Default services:**'))
subcat.extend(utils.rstlist(services))
return [subcat]
def variable_reference(v, st_type, in_type, doc):
lines = [v, "-" * len(v), ""]
docstring = prepare_docstring(doc)
lines.extend([docstring[0], ""])
lines.extend([":Storage Type: ``%s``" % st_type.__name__, ":Input Type: ``%s``" % in_type.__name__, ""])
lines.extend(docstring[1:])
lines.append("")
return lines
def make_rst(self):
classname = self.arguments[0]
cls = import_class(classname)
sublime_caption = self.get_sublime_caption(cls.__name__)
doc = cls.__doc__
yield ''
yield '.. sublime:windowcommand:: {}'.format(sublime_caption)
yield ''
if doc:
for line in prepare_docstring(doc):
yield ' ' + line
yield ''
def _docstr2rst(self, func):
docstring = func.__doc__
rst_lines = prepare_docstring(docstring)
rst_lines = GoogleDocstring(
docstring=rst_lines,
what='function',
config=Config(napoleon_use_param=True, napoleon_use_rtype=True)
).lines()
rst_lines = NumpyDocstring(
docstring=rst_lines,
what='function',
config=Config(napoleon_use_param=True, napoleon_use_rtype=True)
).lines()
return rst_lines
def make_rst(self, qref=False):
app = import_object(self.arguments[0])
routes = self.inspect_routes(app)
if 'view' in self.groupby:
routes = self.groupby_view(routes)
for method, paths, view_func, view_doc in routes:
docstring = prepare_docstring(view_doc)
if qref:
for path in paths:
row = quickref_directive(method, path, docstring)
yield row
else:
for line in http_directive(method, paths, docstring):
yield line
