From: Sergei Izmailov <sergei.a.izmailov@gmail.com>
Date: Tue, 30 Jun 2020 12:44:00 +0000 (+0300)
Subject: documentation/python: use full pybind11 docstrings.
X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~cjwatson/git?a=commitdiff_plain;h=1c9d4bb1e60fa99fdbec0dc1ab2832bf901f2b04;p=blog.git

documentation/python: use full pybind11 docstrings.
---

diff --git a/documentation/python.py b/documentation/python.py
index ce56d196..6b8288a5 100755
--- a/documentation/python.py
+++ b/documentation/python.py
@@ -969,17 +969,17 @@ def parse_pybind_signature(state: State, referrer_path: List[str], signature: st
         end = original_signature.find('\n')
         logging.warning("cannot parse pybind11 function signature %s: %s", (original_signature[:end if end != -1 else None]), e)
         if end != -1 and len(original_signature) > end + 1 and original_signature[end + 1] == '\n':
-            summary = inspect.cleandoc(original_signature[end + 1:]).partition('\n\n')[0]
+            docstring = inspect.cleandoc(original_signature[end + 1:])
         else:
-            summary = ''
-        return (name, summary, [('…', None, None, None)], None, None)
+            docstring = ''
+        return (name, docstring, [('…', None, None, None)], None, None)
 
     if len(signature) > 1 and signature[1] == '\n':
-        summary = inspect.cleandoc(signature[2:]).partition('\n\n')[0]
+        docstring = inspect.cleandoc(signature[2:])
     else:
-        summary = ''
+        docstring = ''
 
-    return (name, summary, args, return_type, return_type_link)
+    return (name, docstring, args, return_type, return_type_link)
 
 def parse_pybind_docstring(state: State, referrer_path: List[str], doc: str) -> List[Tuple[str, str, List[Tuple[str, str, str]], str]]:
     name = referrer_path[-1]
diff --git a/documentation/test_python/pybind_signatures/pybind_signatures.cpp b/documentation/test_python/pybind_signatures/pybind_signatures.cpp
index e6934b3f..1298708d 100644
--- a/documentation/test_python/pybind_signatures/pybind_signatures.cpp
+++ b/documentation/test_python/pybind_signatures/pybind_signatures.cpp
@@ -79,7 +79,7 @@ PYBIND11_MODULE(pybind_signatures, m) {
 
         .def("full_docstring", &voidFunction, R"(A summary
 
-And a larger docstring as well, which is currently ignored.)");
+And a larger docstring as well.)");
 
     py::class_<MyClass>(m, "MyClass", "My fun class!")
         .def_static("static_function", &MyClass::staticFunction, "Static method with positional-only args")
diff --git a/documentation/test_python/pybind_signatures/pybind_signatures.html b/documentation/test_python/pybind_signatures/pybind_signatures.html
index 19c79b1b..b4095cdc 100644
--- a/documentation/test_python/pybind_signatures/pybind_signatures.html
+++ b/documentation/test_python/pybind_signatures/pybind_signatures.html
@@ -63,8 +63,8 @@
               <span class="m-doc-wrap-bumper">def <a href="#failed_parse_docstring" class="m-doc-self">failed_parse_docstring</a>(</span><span class="m-doc-wrap">…)</span>
             </dt>
             <dd>A failed parse should &lt;strong&gt;also&lt;/strong&gt; escape the docstring</dd>
-            <dt id="full_docstring">
-              <span class="m-doc-wrap-bumper">def <a href="#full_docstring" class="m-doc-self">full_docstring</a>(</span><span class="m-doc-wrap">arg0: int<span class="m-text m-dim">, /</span>) -&gt; None</span>
+            <dt>
+              <span class="m-doc-wrap-bumper">def <a href="#full_docstring" class="m-doc">full_docstring</a>(</span><span class="m-doc-wrap">arg0: int<span class="m-text m-dim">, /</span>) -&gt; None</span>
             </dt>
             <dd>A summary</dd>
             <dt id="overloaded-46f8a">
@@ -153,6 +153,16 @@
             <dd>Returns nothing</dd>
           </dl>
         </section>
+        <section>
+          <h2>Function documentation</h2>
+          <section class="m-doc-details" id="full_docstring"><div>
+            <h3>
+              <span class="m-doc-wrap-bumper">def pybind_signatures.<wbr /></span><span class="m-doc-wrap"><span class="m-doc-wrap-bumper"><a href="#full_docstring" class="m-doc-self">full_docstring</a>(</span><span class="m-doc-wrap">arg0: int<span class="m-text m-dim">, /</span>) -&gt; None</span></span>
+            </h3>
+            <p>A summary</p>
+<p>And a larger docstring as well.</p>
+          </div></section>
+        </section>
       </div>
     </div>
   </div>