From: Vladimír Vondruš Date: Wed, 28 Aug 2019 21:58:46 +0000 (+0200) Subject: documentation/python: don't forget to handle scope for slots as well. X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~cjwatson/git?a=commitdiff_plain;h=5e87492c17c74457586e61a98f485b3274ddf287;p=blog.git documentation/python: don't forget to handle scope for slots as well. --- diff --git a/documentation/python.py b/documentation/python.py index d7c5ca21..647a04df 100755 --- a/documentation/python.py +++ b/documentation/python.py @@ -1460,8 +1460,18 @@ def extract_property_doc(state: State, parent, entry: Empty): out.is_gettable = True out.is_settable = True out.is_deletable = True + + # Call all scope enter hooks before rendering the docs + for hook in state.hooks_pre_scope: + hook(type=entry.type, path=entry.path) + # Unfortunately we can't get any docstring for these out.summary, out.content = extract_docs(state, state.property_docs, entry.type, entry.path, '') + + # Call all scope exit hooks after rendering the docs + for hook in state.hooks_post_scope: + hook(type=entry.type, path=entry.path) + out.has_details = bool(out.content) # First try to get fully dereferenced type hints (with strings diff --git a/documentation/test_python/content/classes.html b/documentation/test_python/content/classes.html index 9199bbd7..f902a7a6 100644 --- a/documentation/test_python/content/classes.html +++ b/documentation/test_python/content/classes.html @@ -27,6 +27,7 @@
  • module docstring_summary This module retains summary from the docstring
  • module submodule This submodule has an external summary.
  • class Class This overwrites the docstring for Class.
    • +
  • class ClassWithSlots This class has slots and those have to be documented externally
  • class ClassWithSummary This class has summary from the docstring
    • diff --git a/documentation/test_python/content/content.ClassWithSlots.html b/documentation/test_python/content/content.ClassWithSlots.html new file mode 100644 index 00000000..c1a7947f --- /dev/null +++ b/documentation/test_python/content/content.ClassWithSlots.html @@ -0,0 +1,55 @@ + + + + + content.ClassWithSlots | My Python Project + + + + + +
    +
    +
    +
    +
    +

    + content.ClassWithSlots class +

    +

    This class has slots and those have to be documented externally

    +
    +

    Contents

    + +
    +
    +

    Properties

    +
    +
    + hello get set del +
    +
    This is a slot, another is this_is_a_slot
    +
    + this_is_a_slot get set del +
    +
    This the other one.
    +
    +
    +
    +
    +
    +
    + + diff --git a/documentation/test_python/content/content.html b/documentation/test_python/content/content.html index 1d8573f8..f603565a 100644 --- a/documentation/test_python/content/content.html +++ b/documentation/test_python/content/content.html @@ -54,6 +54,8 @@ tho.

    class Class
    This overwrites the docstring for Class.
    +
    class ClassWithSlots
    +
    This class has slots and those have to be documented externally
    class ClassWithSummary
    This class has summary from the docstring
    diff --git a/documentation/test_python/content/content/__init__.py b/documentation/test_python/content/content/__init__.py index 46691793..f5b25bb3 100644 --- a/documentation/test_python/content/content/__init__.py +++ b/documentation/test_python/content/content/__init__.py @@ -43,6 +43,11 @@ class Class: class ClassWithSummary: """This class has summary from the docstring""" +class ClassWithSlots: + """This class has slots and those have to be documented externally""" + + __slots__ = ['hello', 'this_is_a_slot'] + class Enum(enum.Enum): """This summary gets ignored""" diff --git a/documentation/test_python/content/docs.rst b/documentation/test_python/content/docs.rst index e9303f12..77d63eec 100644 --- a/documentation/test_python/content/docs.rst +++ b/documentation/test_python/content/docs.rst @@ -75,6 +75,12 @@ This class has external details but summary from the docstring. +.. py:property:: content.ClassWithSlots.hello + :summary: This is a slot, another is :ref:`this_is_a_slot` + +.. py:property:: content.ClassWithSlots.this_is_a_slot + :summary: This the **other one**. + .. py:enum:: content.Enum :summary: This overwrites the docstring for :ref:`Enum`, but doesn't add any detailed block.