From db3570629dd52722f38b7c068d33e9e112973ab9 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Sat, 4 May 2019 21:47:34 +0200 Subject: [PATCH] documentation/python: rename brief to summary. Another doxygen-ism. It made some sense for API docs, but having "brief" and "description" for pages doesn't make any sense at all. Summary and content makes much more sense for pages and since it doesn't make sense to have two types of naming, let's rename it for everything else as well. This is now also in-line with Pelican article metadata and XMLDoc for C# docs, yay. --- doc/documentation/python.rst | 30 +++++----- documentation/python.py | 58 +++++++++---------- documentation/templates/python/class.html | 4 +- documentation/templates/python/classes.html | 4 +- .../templates/python/details-enum.html | 8 +-- .../templates/python/entry-class.html | 2 +- .../templates/python/entry-data.html | 2 +- .../templates/python/entry-enum.html | 2 +- .../templates/python/entry-function.html | 2 +- .../templates/python/entry-module.html | 2 +- .../templates/python/entry-property.html | 2 +- documentation/templates/python/module.html | 4 +- documentation/templates/python/modules.html | 4 +- documentation/templates/python/pages.html | 4 +- 14 files changed, 64 insertions(+), 64 deletions(-) diff --git a/doc/documentation/python.rst b/doc/documentation/python.rst index 918f848e..0c13aed9 100644 --- a/doc/documentation/python.rst +++ b/doc/documentation/python.rst @@ -386,18 +386,18 @@ all found submodules in it are ignored. ------------- 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 @@ -681,7 +681,7 @@ HTML markup without any additional escaping. ======================================= ======================================= 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. @@ -754,7 +754,7 @@ Property Description ======================================= ======================================= :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`_ @@ -767,7 +767,7 @@ Property Description ======================================= ======================================= :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`_ @@ -779,7 +779,7 @@ Property Description 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. @@ -800,7 +800,7 @@ Property Description :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`_ @@ -812,7 +812,7 @@ Property Description 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. @@ -864,7 +864,7 @@ Property Description =================================== =========================================== :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 @@ -882,7 +882,7 @@ Property Description =================================== =========================================== :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 @@ -929,7 +929,7 @@ Property Description :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 @@ -945,4 +945,4 @@ Module/class list is ordered in a way that all modules are before all classes. 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. diff --git a/documentation/python.py b/documentation/python.py index 032089d4..75157a56 100755 --- a/documentation/python.py +++ b/documentation/python.py @@ -97,7 +97,7 @@ class IndexEntry: 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] = [] @@ -227,10 +227,10 @@ def parse_pybind_signature(signature: str) -> Tuple[str, str, List[Tuple[str, st 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:] @@ -249,17 +249,17 @@ def parse_pybind_signature(signature: str) -> Tuple[str, str, List[Tuple[str, st 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 @@ -290,7 +290,7 @@ def parse_pybind_docstring(name: str, doc: str) -> List[Tuple[str, str, List[Tup 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') @@ -331,7 +331,7 @@ def extract_module_doc(path: List[str], module): 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_): @@ -340,7 +340,7 @@ 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_): @@ -354,9 +354,9 @@ 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__) @@ -367,11 +367,11 @@ def extract_enum_doc(state: State, path: List[str], enum_): # 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] @@ -380,7 +380,7 @@ def extract_enum_doc(state: State, path: List[str], enum_): 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(): @@ -390,7 +390,7 @@ def extract_enum_doc(state: State, path: List[str], enum_): # 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 @@ -406,13 +406,13 @@ def extract_function_doc(state: State, parent, path: List[str], function) -> Lis 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 @@ -489,7 +489,7 @@ def extract_function_doc(state: State, parent, path: List[str], function) -> Lis 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): @@ -530,7 +530,7 @@ def extract_property_doc(state: State, path: List[str], property): 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 @@ -553,7 +553,7 @@ def extract_data_doc(parent, path: List[str], data): 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]) @@ -578,7 +578,7 @@ def render_module(state: State, path, module, env): 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 = '.'.join(path + ['']) @@ -594,7 +594,7 @@ def render_module(state: State, path, module, env): 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 @@ -744,7 +744,7 @@ def render_class(state: State, path, class_, env): 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 = '.'.join(path + ['']) @@ -763,7 +763,7 @@ def render_class(state: State, path, class_, env): 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)): diff --git a/documentation/templates/python/class.html b/documentation/templates/python/class.html index 7bbcf1a7..be622826 100644 --- a/documentation/templates/python/class.html +++ b/documentation/templates/python/class.html @@ -14,8 +14,8 @@

{%+ for name, target in page.breadcrumb[:-1] %}{{ name }}.{% endfor %}{{ page.breadcrumb[-1][0] }} class

- {% if page.brief %} -

{{ page.brief }}

+ {% if page.summary %} +

{{ page.summary }}

{% endif %} {% if page.classes or page.classmethods or page.staticmethods or page.methods or page.dunder_methods or page.properties or page.data %}
diff --git a/documentation/templates/python/classes.html b/documentation/templates/python/classes.html index af1d68bd..2f9404dd 100644 --- a/documentation/templates/python/classes.html +++ b/documentation/templates/python/classes.html @@ -7,13 +7,13 @@ {% for i in index.classes recursive %} {% if i.children %}
  • - {{ i.kind }} {{ i.name }} {{ i.brief }} + {{ i.kind }} {{ i.name }} {{ i.summary }}
      {{ loop(i.children)|indent(4, true) }}
    • {% else %} -
  • {{ i.kind }} {{ i.name }}{% if i.is_final %} final{% endif %} {{ i.brief }}
    • +
  • {{ i.kind }} {{ i.name }}{% if i.is_final %} final{% endif %} {{ i.summary }}
    • {% endif %} {% endfor %} diff --git a/documentation/templates/python/details-enum.html b/documentation/templates/python/details-enum.html index 50fb94d7..aac8f6c9 100644 --- a/documentation/templates/python/details-enum.html +++ b/documentation/templates/python/details-enum.html @@ -2,8 +2,8 @@

    class {{ prefix }}{{ enum.name }}({{ enum.base }})

    - {% if enum.brief %} -

    {{ enum.brief }}

    + {% if enum.summary %} +

    {{ enum.summary }}

    {% endif %} {% if enum.has_value_details %} @@ -13,8 +13,8 @@ diff --git a/documentation/templates/python/entry-class.html b/documentation/templates/python/entry-class.html index a294f489..8eb07ec1 100644 --- a/documentation/templates/python/entry-class.html +++ b/documentation/templates/python/entry-class.html @@ -1,2 +1,2 @@
    class {{ class.name }}{% if class.is_deprecated %} deprecated{% endif %}
    -
    {{ class.brief }}
    +
    {{ class.summary }}
    diff --git a/documentation/templates/python/entry-data.html b/documentation/templates/python/entry-data.html index d4e4d881..3e351daa 100644 --- a/documentation/templates/python/entry-data.html +++ b/documentation/templates/python/entry-data.html @@ -3,4 +3,4 @@ {# This has to be here to avoid the newline being eaten #} -
    {{ data.brief }}
    +
    {{ data.summary }}
    diff --git a/documentation/templates/python/entry-enum.html b/documentation/templates/python/entry-enum.html index 1dc1c712..773a0aa6 100644 --- a/documentation/templates/python/entry-enum.html +++ b/documentation/templates/python/entry-enum.html @@ -2,4 +2,4 @@ {% set j = joiner('\n ') %} class {{ enum.name }}{% if enum.base %}({{ enum.base }}){% endif %}: {% for value in enum.values %}{{ j() }}{{ value.name }}{% if value.value is not none %} = {{ value.value }}{% endif %}{% endfor %} -
    {{ enum.brief }}
    +
    {{ enum.summary }}
    diff --git a/documentation/templates/python/entry-function.html b/documentation/templates/python/entry-function.html index c5f43ab3..245f3c19 100644 --- a/documentation/templates/python/entry-function.html +++ b/documentation/templates/python/entry-function.html @@ -2,4 +2,4 @@ {% set j = joiner('\n ' if function.has_complex_params else ' ') %} def {{ function.name }}({% for param in function.params %}{% if loop.index0 %}{% if function.params[loop.index0 - 1].kind == 'POSITIONAL_OR_KEYWORD' and param.kind == 'KEYWORD_ONLY' %}, *,{% 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') %}, /{% endif %}{% endfor %}){% if function.type %} -> {{ function.type }}{% endif %} -
    {{ function.brief }}
    +
    {{ function.summary }}
    diff --git a/documentation/templates/python/entry-module.html b/documentation/templates/python/entry-module.html index 504066de..6b810001 100644 --- a/documentation/templates/python/entry-module.html +++ b/documentation/templates/python/entry-module.html @@ -1,2 +1,2 @@
    module {{ module.name }}{% if module.is_deprecated %} deprecated{% endif %}
    -
    {{ module.brief }}
    +
    {{ module.summary }}
    diff --git a/documentation/templates/python/entry-property.html b/documentation/templates/python/entry-property.html index 8abe1146..78852ee8 100644 --- a/documentation/templates/python/entry-property.html +++ b/documentation/templates/python/entry-property.html @@ -1,4 +1,4 @@
    {{ property.name }}{% if property.type %}: {{ property.type }}{% endif %} get{% if property.is_settable %} set{% endif %}{% if property.is_deletable %} del{% endif %}
    -
    {{ property.brief }}
    +
    {{ property.summary }}
    diff --git a/documentation/templates/python/module.html b/documentation/templates/python/module.html index 0721ba7a..440b8f36 100644 --- a/documentation/templates/python/module.html +++ b/documentation/templates/python/module.html @@ -14,8 +14,8 @@

    {%+ for name, target in page.breadcrumb[:-1] %}{{ name }}.{% endfor %}{{ page.breadcrumb[-1][0] }} module

    - {% if page.brief %} -

    {{ page.brief }}

    + {% if page.summary %} +

    {{ page.summary }}

    {% endif %} {% if page.modules or page.classes or page.functions or page.data %}
    diff --git a/documentation/templates/python/modules.html b/documentation/templates/python/modules.html index 2a833471..0e8f614f 100644 --- a/documentation/templates/python/modules.html +++ b/documentation/templates/python/modules.html @@ -7,13 +7,13 @@ {% for i in index.classes|selectattr('kind', 'equalto', 'module') recursive %} {% if i.children %}
  • - {{ i.kind }} {{ i.name }} {{ i.brief }} + {{ i.kind }} {{ i.name }} {{ i.summary }}
      {{ loop(i.children|selectattr('kind', 'equalto', 'module'))|indent(4, true) }}
    • {% else %} -
  • {{ i.kind }} {{ i.name }} {{ i.brief }}
    • +
  • {{ i.kind }} {{ i.name }} {{ i.summary }}
    • {% endif %} {% endfor %} diff --git a/documentation/templates/python/pages.html b/documentation/templates/python/pages.html index e109dfd4..25c40990 100644 --- a/documentation/templates/python/pages.html +++ b/documentation/templates/python/pages.html @@ -7,13 +7,13 @@ {% for i in index.pages recursive %} {% if i.children %}
  • - {{ i.name }} {{ i.brief }} + {{ i.name }} {{ i.summary }}
      {{ loop(i.children)|indent(4, true) }}
    • {% else %} -
  • {{ i.name }} {{ i.brief }}
    • +
  • {{ i.name }} {{ i.summary }}
    • {% endif %} {% endfor %} -- 2.30.2
    {{ value.name }} - {% if value.brief %} -

    {{ value.brief }}

    + {% if value.summary %} +

    {{ value.summary }}

    {% endif %}