chiark / gitweb /
~cjwatson / blog.git / commitdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | patch | inline | side by side (parent: 97e5cca)
documentation/python: use external summary only if it's actually there.
authorVladimír Vondruš <mosra@centrum.cz>
Tue, 21 May 2019 18:04:10 +0000 (20:04 +0200)
committerVladimír Vondruš <mosra@centrum.cz>
Tue, 21 May 2019 19:00:06 +0000 (21:00 +0200)
documentation/python.py patch | blob | history
documentation/test_python/content/classes.html patch | blob | history
documentation/test_python/content/content.AnotherClass.html [new file with mode: 0644] patch | blob
documentation/test_python/content/content.html patch | blob | history
documentation/test_python/content/content.py patch | blob | history
documentation/test_python/content/docs.rst patch | blob | history
documentation/test_python/test_content.py patch | blob | history

diff --git a/documentation/python.py b/documentation/python.py
index 9d49ffbfc242ac12277b15bf40a5792b85b3404c..5c3a25561acbb0d5d53edea2a063ee8347e81b92 100755 (executable)
--- a/documentation/python.py
+++ b/documentation/python.py
@@ -318,7 +318,7 @@ def parse_pybind_docstring(state: State, name: str, doc: str) -> List[Tuple[str,
 def extract_summary(state: State, external_docs, path: List[str], doc: str) -> str:
     # Prefer external docs, if available
     path_str = '.'.join(path)
-    if path_str in external_docs:
+    if path_str in external_docs and external_docs[path_str]['summary']:
         return render_inline_rst(state, external_docs[path_str]['summary'])
 
     if not doc: return '' # some modules (xml.etree) have that :(
diff --git a/documentation/test_python/content/classes.html b/documentation/test_python/content/classes.html
index 9472999b2a5a4fdce0a4d37aa97cd285c1ad0f40..ff357b8eeadc01db8206585c3a4929e472045e79 100644 (file)
--- a/documentation/test_python/content/classes.html
+++ b/documentation/test_python/content/classes.html
@@ -24,6 +24,7 @@
           <li class="m-doc-collapsible">
             <a href="#" onclick="return toggle(this)">module</a> <a href="content.html" class="m-doc">content</a> <span class="m-doc">This overwrites the docstring for <code>content</code>.</span>
             <ul class="m-doc">
+              <li>class <a href="content.AnotherClass.html" class="m-doc">AnotherClass</a> <span class="m-doc">This class has summary from the docstring</span></li>
               <li>class <a href="content.Class.html" class="m-doc">Class</a> <span class="m-doc">This overwrites the docstring for <code>content.Class</code>.</span></li>
             </ul>
           </li>
diff --git a/documentation/test_python/content/content.AnotherClass.html b/documentation/test_python/content/content.AnotherClass.html
new file mode 100644 (file)
index 0000000..1075f47
--- /dev/null
+++ b/documentation/test_python/content/content.AnotherClass.html
@@ -0,0 +1,32 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <title>content.AnotherClass | 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>AnotherClass <span class="m-thin">class</span>
+        </h1>
+        <p>This class has summary from the docstring</p>
+<p>This class has external details but summary from the docstring.</p>
+      </div>
+    </div>
+  </div>
+</article></main>
+</body>
+</html>
diff --git a/documentation/test_python/content/content.html b/documentation/test_python/content/content.html
index a44c9171e719504ee34a874bd34f5cc59e5334c4..01edd0af6957540cf35a839165c8373315d58752 100644 (file)
--- a/documentation/test_python/content/content.html
+++ b/documentation/test_python/content/content.html
@@ -40,6 +40,8 @@ tho.</p>
         <section id="classes">
           <h2><a href="#classes">Classes</a></h2>
           <dl class="m-doc">
+            <dt>class <a href="content.AnotherClass.html" class="m-doc">AnotherClass</a></dt>
+            <dd>This class has summary from the docstring</dd>
             <dt>class <a href="content.Class.html" class="m-doc">Class</a></dt>
             <dd>This overwrites the docstring for <code>content.Class</code>.</dd>
           </dl>
diff --git a/documentation/test_python/content/content.py b/documentation/test_python/content/content.py
index ea2d6f1b625f8945534c511b7f33df1784ce7251..185d93a07a6076d14e87a27b8705f626440fa61d 100644 (file)
--- a/documentation/test_python/content/content.py
+++ b/documentation/test_python/content/content.py
@@ -3,4 +3,7 @@
 class Class:
     """And this class summary, not shown either"""
 
+class AnotherClass:
+    """This class has summary from the docstring"""
+
 CONSTANT: float = 3.14
diff --git a/documentation/test_python/content/docs.rst b/documentation/test_python/content/docs.rst
index 3c6ceb0558d366ca90e58539c3dbf7d9154f2535..0161c2ce82f79d31a821476bc30f8ba3b204702e 100644 (file)
--- a/documentation/test_python/content/docs.rst
+++ b/documentation/test_python/content/docs.rst
@@ -10,5 +10,9 @@
     This is detailed class docs. Here I *also* hate how it needs to be
     indented.
 
+.. py:class:: content.AnotherClass
+
+    This class has external details but summary from the docstring.
+
 .. py:data:: content.CONSTANT
     :summary: This is finally a docstring for ``content.CONSTANT``
diff --git a/documentation/test_python/test_content.py b/documentation/test_python/test_content.py
index bdb77724c0bfd49950fc544661b28d1ca228595b..e61778a1b71419adb12dae7b1e926d2028617a87 100644 (file)
--- a/documentation/test_python/test_content.py
+++ b/documentation/test_python/test_content.py
@@ -38,3 +38,4 @@ class Content(BaseInspectTestCase):
         self.assertEqual(*self.actual_expected_contents('classes.html'))
         self.assertEqual(*self.actual_expected_contents('content.html'))
         self.assertEqual(*self.actual_expected_contents('content.Class.html'))
+        self.assertEqual(*self.actual_expected_contents('content.AnotherClass.html'))
Colin Watson's blog