From: Vladimír Vondruš <mosra@centrum.cz>
Date: Wed, 5 Jan 2022 21:43:06 +0000 (+0100)
Subject: documentation/python: try breaking the pybind11 docstring parser.
X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~cjwatson/git?a=commitdiff_plain;h=d3003a7cb7b546a3b2d610538a70a21046995855;p=blog.git

documentation/python: try breaking the pybind11 docstring parser.

Yeah, not really great.
---

diff --git a/documentation/test_python/pybind_signatures/pybind_signatures.cpp b/documentation/test_python/pybind_signatures/pybind_signatures.cpp
index 1298708d..bc8c9c34 100644
--- a/documentation/test_python/pybind_signatures/pybind_signatures.cpp
+++ b/documentation/test_python/pybind_signatures/pybind_signatures.cpp
@@ -79,7 +79,17 @@ PYBIND11_MODULE(pybind_signatures, m) {
 
         .def("full_docstring", &voidFunction, R"(A summary
 
-And a larger docstring as well.)");
+And a larger docstring as well.)")
+        .def("full_docstring_overloaded", &tenOverloads<int, int>, R"(An overload summary
+
+This function takes a value of 2. full_docstring_overloaded(a: float, b: float)
+takes just 3 instead.)")
+        .def("full_docstring_overloaded", &tenOverloads<float, float>, R"(Another overload summary
+
+This overload, however, takes just a 32-bit (or 64-bit) floating point value of
+3. full_docstring_overloaded(a: int, b: int)
+takes just 2. There's nothing for 4. full_docstring_overloaded(a: poo, b: foo)
+could be another, but it's not added yet.)");
 
     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 b4095cdc..687d6b00 100644
--- a/documentation/test_python/pybind_signatures/pybind_signatures.html
+++ b/documentation/test_python/pybind_signatures/pybind_signatures.html
@@ -67,6 +67,16 @@
               <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>
+              <span class="m-doc-wrap-bumper">def <a href="#full_docstring_overloaded-e9329" class="m-doc">full_docstring_overloaded</a>(</span><span class="m-doc-wrap">arg0: int,
+              arg1: int<span class="m-text m-dim">, /</span>) -&gt; None</span>
+            </dt>
+            <dd>An overload summary</dd>
+            <dt>
+              <span class="m-doc-wrap-bumper">def <a href="#full_docstring_overloaded-fe11a" class="m-doc">full_docstring_overloaded</a>(</span><span class="m-doc-wrap">arg0: float,
+              arg1: float<span class="m-text m-dim">, /</span>) -&gt; None</span>
+            </dt>
+            <dd>Another overload summary</dd>
             <dt id="overloaded-46f8a">
               <span class="m-doc-wrap-bumper">def <a href="#overloaded-46f8a" class="m-doc-self">overloaded</a>(</span><span class="m-doc-wrap">arg0: int<span class="m-text m-dim">, /</span>) -&gt; str</span>
             </dt>
@@ -162,6 +172,26 @@
             <p>A summary</p>
 <p>And a larger docstring as well.</p>
           </div></section>
+          <section class="m-doc-details" id="full_docstring_overloaded-e9329"><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_overloaded-e9329" class="m-doc-self">full_docstring_overloaded</a>(</span><span class="m-doc-wrap">arg0: int,
+              arg1: int<span class="m-text m-dim">, /</span>) -&gt; None</span></span>
+            </h3>
+            <p>An overload summary</p>
+<p>This function takes a value of 2. full_docstring_overloaded(a: float, b: float)
+takes just 3 instead.</p>
+          </div></section>
+          <section class="m-doc-details" id="full_docstring_overloaded-fe11a"><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_overloaded-fe11a" class="m-doc-self">full_docstring_overloaded</a>(</span><span class="m-doc-wrap">arg0: float,
+              arg1: float<span class="m-text m-dim">, /</span>) -&gt; None</span></span>
+            </h3>
+            <p>Another overload summary</p>
+<p>This overload, however, takes just a 32-bit (or 64-bit) floating point value of
+3. full_docstring_overloaded(a: int, b: int)
+takes just 2. There&#x27;s nothing for 4. full_docstring_overloaded(a: poo, b: foo)
+could be another, but it&#x27;s not added yet.</p>
+          </div></section>
         </section>
       </div>
     </div>