-------------
The first paragraph of a module-level, class-level and function-level docstring
-is used as a brief documentation, copied as-is to the output without formatting
-it in any way.
+is used as a doc summary, copied as-is to the output without formatting it in
+any way.
.. code:: py
- """Module brief docs"""
+ """Module summary"""
class Foo:
- """Class brief docs"""
+ """Class summary"""
def bar(self):
- """Function brief docs"""
+ """Function summary"""
.. block-warning:: Limitations
======================================= =======================================
Property Description
======================================= =======================================
-:py:`page.brief` Brief docs
+:py:`page.summary` Doc summary
:py:`page.url` File URL
:py:`page.breadcrumb` List of :py:`(title, URL)` tuples for
breadcrumb navigation.
======================================= =======================================
:py:`module.url` URL of detailed module documentation
:py:`module.name` Module name
-:py:`module.brief` Brief docs
+:py:`module.summary` Doc summary
======================================= =======================================
`Class properties`_
======================================= =======================================
:py:`class_.url` URL of detailed class documentation
:py:`class_.name` Class name
-:py:`class_.brief` Brief docs
+:py:`class_.summary` Doc summary
======================================= =======================================
`Enum properties`_
Property Description
======================================= =======================================
:py:`enum.name` Enum name
-:py:`enum.brief` Brief docs
+:py:`enum.summary` Doc summary
:py:`enum.base` Base class from which the enum is
derived. Set to :py:`None` if no base
class information is available.
:py:`value.name` Value name
:py:`value.value` Value value. Set to :py:`None` if no value is
available.
-:py:`value.brief` Value brief docs
+:py:`value.summary` Value doc summary
=========================== ===================================================
`Function properties`_
Property Description
=================================== ===========================================
:py:`function.name` Function name
-:py:`function.brief` Brief docs
+:py:`function.summary` Doc summary
:py:`function.type` Function return type annotation [1]_
:py:`function.params` List of function parameters. See below for
details.
=================================== ===========================================
:py:`property.name` Property name
:py:`property.type` Property getter return type annotation [1]_
-:py:`property.brief` Brief docs
+:py:`property.summary` Doc summary
:py:`property.is_writable` If the property is writable
:py:`property.is_deletable` If the property is deletable with :py:`del`
:py:`property.has_details` If there is enough content for the full
=================================== ===========================================
:py:`data.name` Data name
:py:`data.type` Data type
-:py:`data.brief` Brief docs. Currently always empty.
+:py:`data.summary` Doc summary. Currently always empty.
:py:`data.value` Data value representation
:py:`data.has_details` If there is enough content for the full
description block. Currently always set to
:py:`'class'` or :py:`'page'`)
:py:`i.name` Name
:py:`i.url` URL of the file with detailed documentation
-:py:`i.brief` Brief documentation
+:py:`i.summary` Doc summary
:py:`i.has_nestable_children` If the list has nestable children (i.e., dirs
or namespaces)
:py:`i.children` Recursive list of child entries
there is detailed description, function parameter documentation or
*documented* enum value listing that makes it worth to render the full
description block. If :py:`False`, the member should be included only in
- the brief listing on top of the page to avoid unnecessary repetition.
+ the summary listing on top of the page to avoid unnecessary repetition.
self.kind: str
self.name: str
self.url: str
- self.brief: str
+ self.summary: str
self.has_nestaable_children: bool = False
self.children: List[IndexEntry] = []
end = original_signature.find('\n')
logging.warning("cannot parse pybind11 function signature %s", original_signature[:end])
if end != -1 and len(original_signature) > end + 1 and original_signature[end + 1] == '\n':
- brief = extract_brief(original_signature[end + 1:])
+ summary = extract_summary(original_signature[end + 1:])
else:
- brief = ''
- return (name, brief, [('…', None, None)], None)
+ summary = ''
+ return (name, summary, [('…', None, None)], None)
signature = signature[2:]
end = original_signature.find('\n')
logging.warning("cannot parse pybind11 function signature %s", original_signature[:end])
if end != -1 and len(original_signature) > end + 1 and original_signature[end + 1] == '\n':
- brief = extract_brief(original_signature[end + 1:])
+ summary = extract_summary(original_signature[end + 1:])
else:
- brief = ''
- return (name, brief, [('…', None, None)], None)
+ summary = ''
+ return (name, summary, [('…', None, None)], None)
if len(signature) > 1 and signature[1] == '\n':
- brief = extract_brief(signature[2:])
+ summary = extract_summary(signature[2:])
else:
- brief = ''
+ summary = ''
- return (name, brief, args, return_type)
+ return (name, summary, args, return_type)
def parse_pybind_docstring(name: str, doc: str) -> List[Tuple[str, str, List[Tuple[str, str, str]], str]]:
# Multiple overloads, parse each separately
else:
return [parse_pybind_signature(doc)]
-def extract_brief(doc: str) -> str:
+def extract_summary(doc: str) -> str:
if not doc: return '' # some modules (xml.etree) have that :(
doc = inspect.cleandoc(doc)
end = doc.find('\n\n')
out = Empty()
out.url = make_url(path)
out.name = path[-1]
- out.brief = extract_brief(module.__doc__)
+ out.summary = extract_summary(module.__doc__)
return out
def extract_class_doc(path: List[str], class_):
out = Empty()
out.url = make_url(path)
out.name = path[-1]
- out.brief = extract_brief(class_.__doc__)
+ out.summary = extract_summary(class_.__doc__)
return out
def extract_enum_doc(state: State, path: List[str], enum_):
if issubclass(enum_, enum.Enum):
# Enum doc is by default set to a generic value. That's useless as well.
if enum_.__doc__ == 'An enumeration.':
- out.brief = ''
+ out.summary = ''
else:
- out.brief = extract_brief(enum_.__doc__)
+ out.summary = extract_summary(enum_.__doc__)
out.base = extract_type(enum_.__base__)
# Value doc gets by default inherited from the enum, that's useless
if i.__doc__ == enum_.__doc__:
- value.brief = ''
+ value.summary = ''
else:
- value.brief = extract_brief(i.__doc__)
+ value.summary = extract_summary(i.__doc__)
- if value.brief:
+ if value.summary:
out.has_details = True
out.has_value_details = True
out.values += [value]
elif state.config['PYBIND11_COMPATIBILITY']:
assert hasattr(enum_, '__members__')
- out.brief = extract_brief(enum_.__doc__)
+ out.summary = extract_summary(enum_.__doc__)
out.base = None
for name, v in enum_.__members__.items():
# TODO: once https://github.com/pybind/pybind11/pull/1160 is
# released, extract from class docs (until then the class
# docstring is duplicated here, which is useless)
- value.brief = ''
+ value.summary = ''
out.values += [value]
return out
if state.config['PYBIND11_COMPATIBILITY'] and function.__doc__.startswith(path[-1]):
funcs = parse_pybind_docstring(path[-1], function.__doc__)
overloads = []
- for name, brief, args, type in funcs:
+ for name, summary, args, type in funcs:
out = Empty()
out.name = path[-1]
out.params = []
out.has_complex_params = False
out.has_details = False
- out.brief = brief
+ out.summary = summary
# Don't show None return type for void functions
out.type = None if type == 'None' else type
out.params = []
out.has_complex_params = False
out.has_details = False
- out.brief = extract_brief(function.__doc__)
+ out.summary = extract_summary(function.__doc__)
# Decide if classmethod or staticmethod in case this is a method
if inspect.isclass(parent):
out = Empty()
out.name = path[-1]
- out.brief = extract_brief(property.__doc__)
+ out.summary = extract_summary(property.__doc__)
out.is_settable = property.fset is not None
out.is_deletable = property.fdel is not None
out.has_details = False
out = Empty()
out.name = path[-1]
# Welp. https://stackoverflow.com/questions/8820276/docstring-for-variable
- out.brief = ''
+ out.summary = ''
out.has_details = False
if hasattr(parent, '__annotations__') and out.name in parent.__annotations__:
out.type = extract_annotation(parent.__annotations__[out.name])
breadcrumb += [(i, url_base + 'html')]
page = Empty()
- page.brief = extract_brief(module.__doc__)
+ page.summary = extract_summary(module.__doc__)
page.url = breadcrumb[-1][1]
page.breadcrumb = breadcrumb
page.prefix_wbr = '.<wbr />'.join(path + [''])
index_entry.kind = 'module'
index_entry.name = breadcrumb[-1][0]
index_entry.url = page.url
- index_entry.brief = page.brief
+ index_entry.summary = page.summary
# This is actually complicated -- if the module defines __all__, use that.
# The __all__ is meant to expose the public API, so we don't filter out
breadcrumb += [(i, url_base + 'html')]
page = Empty()
- page.brief = extract_brief(class_.__doc__)
+ page.summary = extract_summary(class_.__doc__)
page.url = breadcrumb[-1][1]
page.breadcrumb = breadcrumb
page.prefix_wbr = '.<wbr />'.join(path + [''])
index_entry.kind = 'class'
index_entry.name = breadcrumb[-1][0]
index_entry.url = page.url
- index_entry.brief = page.brief
+ index_entry.summary = page.summary
# Get inner classes
for name, object in inspect.getmembers(class_, lambda o: inspect.isclass(o) and not is_enum(state, o)):
<h1>
{%+ for name, target in page.breadcrumb[:-1] %}<span class="m-breadcrumb"><a href="{{ target }}">{{ name }}</a>.<wbr/></span>{% endfor %}{{ page.breadcrumb[-1][0] }} <span class="m-thin">class</span>
</h1>
- {% if page.brief %}
- <p>{{ page.brief }}</p>
+ {% if page.summary %}
+ <p>{{ page.summary }}</p>
{% endif %}
{% if page.classes or page.classmethods or page.staticmethods or page.methods or page.dunder_methods or page.properties or page.data %}
<div class="m-block m-default">
{% for i in index.classes recursive %}
{% if i.children %}
<li class="m-doc-collapsible{% if loop.depth > CLASS_INDEX_EXPAND_LEVELS or (i.kind != 'module' and not CLASS_INDEX_EXPAND_INNER) %} collapsed{% endif %}">
- <a href="#" onclick="return toggle(this)">{{ i.kind }}</a> <a href="{{ i.url }}" class="m-doc">{{ i.name }}</a> <span class="m-doc">{{ i.brief }}</span>
+ <a href="#" onclick="return toggle(this)">{{ i.kind }}</a> <a href="{{ i.url }}" class="m-doc">{{ i.name }}</a> <span class="m-doc">{{ i.summary }}</span>
<ul class="m-doc">
{{ loop(i.children)|indent(4, true) }}
</ul>
</li>
{% else %}
- <li>{{ i.kind }} <a href="{{ i.url }}" class="m-doc">{{ i.name }}</a>{% if i.is_final %} <span class="m-label m-flat m-warning">final</span>{% endif %} <span class="m-doc">{{ i.brief }}</span></li>
+ <li>{{ i.kind }} <a href="{{ i.url }}" class="m-doc">{{ i.name }}</a>{% if i.is_final %} <span class="m-label m-flat m-warning">final</span>{% endif %} <span class="m-doc">{{ i.summary }}</span></li>
{% endif %}
{% endfor %}
</ul>
<h3>
class {{ prefix }}<a href="" class="m-doc-self">{{ enum.name }}</a>({{ enum.base }})
</h3>
- {% if enum.brief %}
- <p>{{ enum.brief }}</p>
+ {% if enum.summary %}
+ <p>{{ enum.summary }}</p>
{% endif %}
{% if enum.has_value_details %}
<table class="m-table m-fullwidth m-flat m-doc">
<tr>
<td><a href="" class="m-doc-self">{{ value.name }}</a></td>
<td>
- {% if value.brief %}
- <p>{{ value.brief }}</p>
+ {% if value.summary %}
+ <p>{{ value.summary }}</p>
{% endif %}
</td>
</tr>
<dt>class <a href="{{ class.url }}" class="m-doc">{{ class.name }}</a>{% if class.is_deprecated %} <span class="m-label m-danger">deprecated</span>{% endif %}</dt>
- <dd>{{ class.brief }}</dd>
+ <dd>{{ class.summary }}</dd>
{# This has to be here to avoid the newline being eaten #}
</dt>
- <dd>{{ data.brief }}</dd>
+ <dd>{{ data.summary }}</dd>
{% set j = joiner('\n ') %}
<span class="m-doc-wrap-bumper">class <a href="" class="m-doc{% if not enum.has_details %}-self{% endif %}">{{ enum.name }}</a>{% if enum.base %}({{ enum.base }}){% endif %}: </span><span class="m-doc-wrap">{% for value in enum.values %}{{ j() }}<a href="" class="m-doc{% if not enum.has_details %}-self{% endif %}">{{ value.name }}</a>{% if value.value is not none %} = {{ value.value }}{% endif %}{% endfor %}</span>
</dt>
- <dd>{{ enum.brief }}</dd>
+ <dd>{{ enum.summary }}</dd>
{% set j = joiner('\n ' if function.has_complex_params else ' ') %}
<span class="m-doc-wrap-bumper">def <a href="" class="m-doc{% if not function.has_details %}-self{% endif %}">{{ function.name }}</a>(</span><span class="m-doc-wrap">{% for param in function.params %}{% if loop.index0 %}{% if function.params[loop.index0 - 1].kind == 'POSITIONAL_OR_KEYWORD' and param.kind == 'KEYWORD_ONLY' %},<span class="m-text m-dim"> *,</span>{% else %},{% endif %}{% endif %}{{ j() }}{% if param.kind == 'VAR_POSITIONAL' %}*{% elif param.kind == 'VAR_KEYWORD' %}**{% endif %}{{ param.name }}{% if param.type %}: {{ param.type }}{% endif %}{% if param.default %} = {{ param.default }}{% endif %}{% if param.kind == 'POSITIONAL_ONLY' and (loop.last or function.params[loop.index0 + 1].kind != 'POSITIONAL_ONLY') %}<span class="m-text m-dim">, /</span>{% endif %}{% endfor %}){% if function.type %} -> {{ function.type }}{% endif %}</span>
</dt>
- <dd>{{ function.brief }}</dd>
+ <dd>{{ function.summary }}</dd>
<dt>module <a href="{{ module.url }}" class="m-doc">{{ module.name }}</a>{% if module.is_deprecated %} <span class="m-label m-danger">deprecated</span>{% endif %}</dt>
- <dd>{{ module.brief }}</dd>
+ <dd>{{ module.summary }}</dd>
<dt>
<a href="" class="m-doc{% if not property.has_details %}-self{% endif %}">{{ property.name }}</a>{% if property.type %}: {{ property.type }}{% endif %} <span class="m-label m-flat {% if property.is_settable %}m-success{% else %}m-warning{% endif %}">get{% if property.is_settable %} set{% endif %}{% if property.is_deletable %} del{% endif %}</span>
</dt>
- <dd>{{ property.brief }}</dd>
+ <dd>{{ property.summary }}</dd>
<h1>
{%+ for name, target in page.breadcrumb[:-1] %}<span class="m-breadcrumb"><a href="{{ target }}">{{ name }}</a>.<wbr/></span>{% endfor %}{{ page.breadcrumb[-1][0] }} <span class="m-thin">module</span>
</h1>
- {% if page.brief %}
- <p>{{ page.brief }}</p>
+ {% if page.summary %}
+ <p>{{ page.summary }}</p>
{% endif %}
{% if page.modules or page.classes or page.functions or page.data %}
<div class="m-block m-default">
{% for i in index.classes|selectattr('kind', 'equalto', 'module') recursive %}
{% if i.children %}
<li class="m-doc-collapsible">
- <a href="#" onclick="return toggle(this)">{{ i.kind }}</a> <a href="{{ i.url }}" class="m-doc">{{ i.name }}</a> <span class="m-doc">{{ i.brief }}</span>
+ <a href="#" onclick="return toggle(this)">{{ i.kind }}</a> <a href="{{ i.url }}" class="m-doc">{{ i.name }}</a> <span class="m-doc">{{ i.summary }}</span>
<ul class="m-doc">
{{ loop(i.children|selectattr('kind', 'equalto', 'module'))|indent(4, true) }}
</ul>
</li>
{% else %}
- <li>{{ i.kind }} <a href="{{ i.url }}" class="m-doc">{{ i.name }}</a> <span class="m-doc">{{ i.brief }}</span></li>
+ <li>{{ i.kind }} <a href="{{ i.url }}" class="m-doc">{{ i.name }}</a> <span class="m-doc">{{ i.summary }}</span></li>
{% endif %}
{% endfor %}
</ul>
{% for i in index.pages recursive %}
{% if i.children %}
<li class="m-doc-collapsible">
- <a href="#" onclick="return toggle(this)"></a><a href="{{ i.url }}" class="m-doc">{{ i.name }}</a> <span class="m-doc">{{ i.brief }}</span>
+ <a href="#" onclick="return toggle(this)"></a><a href="{{ i.url }}" class="m-doc">{{ i.name }}</a> <span class="m-doc">{{ i.summary }}</span>
<ul class="m-doc">
{{ loop(i.children)|indent(4, true) }}
</ul>
</li>
{% else %}
- <li><a href="{{ i.url }}" class="m-doc">{{ i.name }}</a> <span class="m-doc">{{ i.brief }}</span></li>
+ <li><a href="{{ i.url }}" class="m-doc">{{ i.name }}</a> <span class="m-doc">{{ i.summary }}</span></li>
{% endif %}
{% endfor %}
</ul>
~cjwatson / blog.git / commitdiff