From b7db5f95c580c41ac6324eac6c89a507bee7c8ec Mon Sep 17 00:00:00 2001 From: Sergei Izmailov Date: Mon, 13 Jul 2020 01:48:43 +0300 Subject: [PATCH 1/2] Move exceptions to a separate section --- documentation/python.py | 18 +++++++++++++++--- documentation/templates/python/class.html | 15 ++++++++++++++- .../templates/python/entry-class.html | 2 +- documentation/templates/python/module.html | 13 +++++++++++++ documentation/test_python/content/classes.html | 8 +++++++- .../test_python/content/content.Class.html | 8 ++++++++ documentation/test_python/content/content.html | 8 ++++++++ .../test_python/content/content/__init__.py | 6 ++++++ .../test_python/inspect_string/classes.html | 2 +- .../inspect_string/inspect_string.html | 10 ++++++++-- 10 files changed, 81 insertions(+), 9 deletions(-) diff --git a/documentation/python.py b/documentation/python.py index 0c750426..24ccc14b 100755 --- a/documentation/python.py +++ b/documentation/python.py @@ -398,6 +398,7 @@ def crawl_class(state: State, path: List[str], class_): class_entry.type = EntryType.CLASS class_entry.object = class_ class_entry.path = path + class_entry.is_exception = issubclass(class_, BaseException) class_entry.css_classes = ['m-doc'] class_entry.url = state.config['URL_FORMATTER'](EntryType.CLASS, path)[1] class_entry.members = [] @@ -1264,6 +1265,7 @@ def extract_class_doc(state: State, entry: Empty): out = Empty() out.url = entry.url out.name = entry.path[-1] + out.is_exception = entry.is_exception out.summary = extract_docs(state, state.class_docs, entry.type, entry.path, entry.object.__doc__, summary_only=True) # Call all scope exit hooks last @@ -1913,6 +1915,7 @@ def render_module(state: State, path, module, env): page.enums = [] page.functions = [] page.data = [] + page.exceptions = [] page.has_enum_details = False page.has_function_details = False page.has_data_details = False @@ -1933,7 +1936,11 @@ def render_module(state: State, path, module, env): if member_entry.type == EntryType.MODULE: page.modules += [extract_module_doc(state, member_entry)] elif member_entry.type == EntryType.CLASS: - page.classes += [extract_class_doc(state, member_entry)] + doc_ = extract_class_doc(state, member_entry) + if doc_.is_exception: + page.exceptions += [doc_] + else: + page.classes += [doc_] elif member_entry.type == EntryType.ENUM: enum_ = extract_enum_doc(state, member_entry) page.enums += [enum_] @@ -2004,6 +2011,7 @@ def render_class(state: State, path, class_, env): page.methods = [] page.properties = [] page.data = [] + page.exceptions = [] page.has_enum_details = False page.has_function_details = False page.has_property_details = False @@ -2024,7 +2032,11 @@ def render_class(state: State, path, class_, env): logging.warning("%s is undocumented", subpath_str) if member_entry.type == EntryType.CLASS: - page.classes += [extract_class_doc(state, member_entry)] + doc_ = extract_class_doc(state, member_entry) + if doc_.is_exception: + page.exceptions += [doc_] + else: + page.classes += [doc_] elif member_entry.type == EntryType.ENUM: enum_ = extract_enum_doc(state, member_entry) page.enums += [enum_] @@ -2547,7 +2559,7 @@ def path_to_url(path): # from the top-level index list and gather all class/module children. def fetch_class_index(entry): index_entry = Empty() - index_entry.kind = 'module' if entry.type == EntryType.MODULE else 'class' + index_entry.kind = 'module' if entry.type == EntryType.MODULE else ('exception' if entry.is_exception else 'class') index_entry.name = entry.path[-1] index_entry.url = state.config['URL_FORMATTER'](entry.type, entry.path)[1] index_entry.summary = entry.summary diff --git a/documentation/templates/python/class.html b/documentation/templates/python/class.html index d6090451..0df68221 100644 --- a/documentation/templates/python/class.html +++ b/documentation/templates/python/class.html @@ -15,7 +15,7 @@ {% block main %}

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

{% if page.summary %}

{{ page.summary }}

@@ -51,6 +51,9 @@

Contents

{% if page.data %}
  • Data
    • {% endif %} + {% if page.exceptions %} +
  • Exceptions
    • + {% endif %} @@ -139,6 +142,16 @@

    Data

    {% endif %} + {% if page.exceptions %} +
    +

    Exceptions

    +
    + {% for exception in page.exceptions %} +{{ entry_class(exception) }} + {% endfor %} +
    +
    + {% endif %} {% if page.has_enum_details %}

    Enum documentation

    diff --git a/documentation/templates/python/entry-class.html b/documentation/templates/python/entry-class.html index 8eb07ec1..8188b8c6 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 %}
    +
    {%if class.is_exception%}exception{%else%}class{%endif%} {{ class.name }}{% if class.is_deprecated %} deprecated{% endif %}
    {{ class.summary }}
    diff --git a/documentation/templates/python/module.html b/documentation/templates/python/module.html index 41acfd56..f3106090 100644 --- a/documentation/templates/python/module.html +++ b/documentation/templates/python/module.html @@ -41,6 +41,9 @@

    Contents

    {% if page.data %}
  • Data
    • {% endif %} + {% if page.exceptions %} +
  • Exceptions
    • + {% endif %} @@ -99,6 +102,16 @@

    Data

    {% endif %} + {% if page.exceptions %} +
    +

    Exceptions

    +
    + {% for exception in page.exceptions %} +{{ entry_class(exception) }} + {% endfor %} +
    +
    + {% endif %} {% if page.has_enum_details %}

    Enum documentation

    diff --git a/documentation/test_python/content/classes.html b/documentation/test_python/content/classes.html index 876306e5..7d79daa9 100644 --- a/documentation/test_python/content/classes.html +++ b/documentation/test_python/content/classes.html @@ -26,10 +26,16 @@

    Classes

    diff --git a/documentation/test_python/content/content.Class.html b/documentation/test_python/content/content.Class.html index a723fbf3..d65e9fdc 100644 --- a/documentation/test_python/content/content.Class.html +++ b/documentation/test_python/content/content.Class.html @@ -35,6 +35,7 @@

    Contents

  • Special methods
  • Properties
  • Data
    • +
  • Exceptions
    • @@ -122,6 +123,13 @@

    Data

    +
    +

    Exceptions

    +
    +
    exception ClassError
    +
    This exception belongs to class
    +
    +

    Method documentation

    diff --git a/documentation/test_python/content/content.html b/documentation/test_python/content/content.html index 3bc42508..b9ee2470 100644 --- a/documentation/test_python/content/content.html +++ b/documentation/test_python/content/content.html @@ -34,6 +34,7 @@

    Contents

  • Enums
  • Functions
  • Data
    • +
  • Exceptions
    • @@ -147,6 +148,13 @@

    Data

    +
    +

    Exceptions

    +
    +
    exception FreeStandingError
    +
    This exception belongs to module
    +
    +

    Enum documentation

    diff --git a/documentation/test_python/content/content/__init__.py b/documentation/test_python/content/content/__init__.py index e555cf0f..15b54ab7 100644 --- a/documentation/test_python/content/content/__init__.py +++ b/documentation/test_python/content/content/__init__.py @@ -48,6 +48,12 @@ def property_exception_docs(self): DATA_WITH_DETAILS: str = 'this blows' + class ClassError(RuntimeError): + """This exception belongs to class""" + +class FreeStandingError(RuntimeError): + """This exception belongs to module""" + class ClassWithSummary: """This class has summary from the docstring""" diff --git a/documentation/test_python/inspect_string/classes.html b/documentation/test_python/inspect_string/classes.html index e6a5895a..275203c5 100644 --- a/documentation/test_python/inspect_string/classes.html +++ b/documentation/test_python/inspect_string/classes.html @@ -43,7 +43,7 @@

    Classes

  • class Foo A class in a subpackage. Shouldn't cause the module tree to have an expander for it.
    • -
  • class DerivedException A class deriving from BaseException, which has the weird args getset_descriptor
    • +
  • exception DerivedException A class deriving from BaseException, which has the weird args getset_descriptor
    • @@ -62,8 +63,6 @@

    Modules

    Classes

    -
    class DerivedException
    -
    A class deriving from BaseException, which has the weird args getset_descriptor
    class Foo
    The foo class
    class FooSlots
    @@ -110,6 +109,13 @@

    Data

    +
    +

    Exceptions

    +
    +
    exception DerivedException
    +
    A class deriving from BaseException, which has the weird args getset_descriptor
    +
    +

    Enum documentation

    From 7778fed122e305ec2775453ffbba173602134465 Mon Sep 17 00:00:00 2001 From: Sergei Izmailov Date: Mon, 13 Jul 2020 01:58:05 +0300 Subject: [PATCH 2/2] Update documentation --- doc/documentation/python.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/doc/documentation/python.rst b/doc/documentation/python.rst index 5496ff5d..83cc4f9f 100644 --- a/doc/documentation/python.rst +++ b/doc/documentation/python.rst @@ -1162,6 +1162,9 @@ Property Description `Function properties`_ for details. :py:`page.methods` List of methods. See `Function properties`_ for details. +:py:`page.exceptions` List of exceptions, does not overlap + with py:`page.classes`. See + `Class properties`_ for details. :py:`page.dunder_methods` List of double-underscored special functions. See `Function properties`_ for details. @@ -1199,6 +1202,7 @@ Property Description ======================================= ======================================= :py:`class_.url` URL of detailed class documentation :py:`class_.name` Class name +:py:`class_.is_exception` Marks exceptions :py:`class_.summary` Doc summary ======================================= ======================================= @@ -1396,7 +1400,8 @@ The form of each list entry is the same: Property Description =============================== =============================================== :py:`i.kind` Entry kind (one of :py:`'module'`, - :py:`'class'` or :py:`'page'`) + :py:`'class'`, :py:`'exception'` or + :py:`'page'`) :py:`i.name` Name :py:`i.url` URL of the file with detailed documentation :py:`i.summary` Doc summary