chiark / gitweb /
~cjwatson / blog.git / commitdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | patch | inline | side by side (parent: 8314af0)
documentation/python: don't forget to handle scope for slots as well.
authorVladimír Vondruš <mosra@centrum.cz>
Wed, 28 Aug 2019 21:58:46 +0000 (23:58 +0200)
committerVladimír Vondruš <mosra@centrum.cz>
Fri, 30 Aug 2019 14:47:58 +0000 (16:47 +0200)
documentation/python.py patch | blob | history
documentation/test_python/content/classes.html patch | blob | history
documentation/test_python/content/content.ClassWithSlots.html [new file with mode: 0644] patch | blob
documentation/test_python/content/content.html patch | blob | history
documentation/test_python/content/content/__init__.py patch | blob | history
documentation/test_python/content/docs.rst patch | blob | history

diff --git a/documentation/python.py b/documentation/python.py
index d7c5ca21f245539d779537996460cba47b0aed35..647a04dffe2d5fe5c115ea4b12048e8195cb1cc3 100755 (executable)
--- 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 9199bbd77f967339c72edff1641e47e8be3b8bd8..f902a7a64d7a5e4f32fe792210269c5540b69078 100644 (file)
--- a/documentation/test_python/content/classes.html
+++ b/documentation/test_python/content/classes.html
@@ -27,6 +27,7 @@
               <li>module <a href="content.docstring_summary.html" class="m-doc">docstring_summary</a> <span class="m-doc">This module retains summary from the docstring</span></li>
               <li>module <a href="content.submodule.html" class="m-doc">submodule</a> <span class="m-doc">This submodule has an external summary.</span></li>
               <li>class <a href="content.Class.html" class="m-doc">Class</a> <span class="m-doc">This overwrites the docstring for <a class="m-doc" href="content.Class.html">Class</a>.</span></li>
+              <li>class <a href="content.ClassWithSlots.html" class="m-doc">ClassWithSlots</a> <span class="m-doc">This class has slots and those have to be documented externally</span></li>
               <li>class <a href="content.ClassWithSummary.html" class="m-doc">ClassWithSummary</a> <span class="m-doc">This class has summary from the docstring</span></li>
             </ul>
           </li>
diff --git a/documentation/test_python/content/content.ClassWithSlots.html b/documentation/test_python/content/content.ClassWithSlots.html
new file mode 100644 (file)
index 0000000..c1a7947
--- /dev/null
+++ b/documentation/test_python/content/content.ClassWithSlots.html
@@ -0,0 +1,55 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <title>content.ClassWithSlots | My Python Project</title>
+  <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Source+Sans+Pro:400,400i,600,600i%7CSource+Code+Pro:400,400i,600" />
+  <link rel="stylesheet" href="m-dark+documentation.compiled.css" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+</head>
+<body>
+<header><nav id="navigation">
+  <div class="m-container">
+    <div class="m-row">
+      <a href="index.html" id="m-navbar-brand" class="m-col-t-8 m-col-m-none m-left-m">My Python Project</a>
+    </div>
+  </div>
+</nav></header>
+<main><article>
+  <div class="m-container m-container-inflatable">
+    <div class="m-row">
+      <div class="m-col-l-10 m-push-l-1">
+        <h1>
+          <span class="m-breadcrumb"><a href="content.html">content</a>.<wbr/></span>ClassWithSlots <span class="m-thin">class</span>
+        </h1>
+        <p>This class has slots and those have to be documented externally</p>
+        <div class="m-block m-default">
+          <h3>Contents</h3>
+          <ul>
+            <li>
+              Reference
+              <ul>
+                <li><a href="#properties">Properties</a></li>
+              </ul>
+            </li>
+          </ul>
+        </div>
+        <section id="properties">
+          <h2><a href="#properties">Properties</a></h2>
+          <dl class="m-doc">
+            <dt id="hello">
+              <a href="#hello" class="m-doc-self">hello</a> <span class="m-label m-flat m-success">get set del</span>
+            </dt>
+            <dd>This is a slot, another is <a class="m-doc" href="content.ClassWithSlots.html#this_is_a_slot">this_is_a_slot</a></dd>
+            <dt id="this_is_a_slot">
+              <a href="#this_is_a_slot" class="m-doc-self">this_is_a_slot</a> <span class="m-label m-flat m-success">get set del</span>
+            </dt>
+            <dd>This the <strong>other one</strong>.</dd>
+          </dl>
+        </section>
+      </div>
+    </div>
+  </div>
+</article></main>
+</body>
+</html>
diff --git a/documentation/test_python/content/content.html b/documentation/test_python/content/content.html
index 1d8573f81ac11981f422c515c053b3991c16b469..f603565a31c216648ee48de101807e67b35db67e 100644 (file)
--- a/documentation/test_python/content/content.html
+++ b/documentation/test_python/content/content.html
@@ -54,6 +54,8 @@ tho.</p>
           <dl class="m-doc">
             <dt>class <a href="content.Class.html" class="m-doc">Class</a></dt>
             <dd>This overwrites the docstring for <a class="m-doc" href="content.Class.html">Class</a>.</dd>
+            <dt>class <a href="content.ClassWithSlots.html" class="m-doc">ClassWithSlots</a></dt>
+            <dd>This class has slots and those have to be documented externally</dd>
             <dt>class <a href="content.ClassWithSummary.html" class="m-doc">ClassWithSummary</a></dt>
             <dd>This class has summary from the docstring</dd>
           </dl>
diff --git a/documentation/test_python/content/content/__init__.py b/documentation/test_python/content/content/__init__.py
index 46691793469ef91302a9158ce81cdf945e7fc79b..f5b25bb3c34ed683411e8ac3cd1be51021e00f36 100644 (file)
--- 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 e9303f126d72bae685436b6d4b33fbf867d88d2d..77d63eec23b0c7b04745a55e5ce2b35947481038 100644 (file)
--- 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.
Colin Watson's blog