chiark / gitweb /
~cjwatson / blog.git / commitdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | patch | inline | side by side (parent: 962247e)
documentation/python: test external doc overload matching with * and /.
authorVladimír Vondruš <mosra@centrum.cz>
Wed, 28 Jun 2023 13:42:36 +0000 (15:42 +0200)
committerVladimír Vondruš <mosra@centrum.cz>
Wed, 28 Jun 2023 14:01:14 +0000 (16:01 +0200)
With the previous commit this now "just works", as the placeholders are
dropped from the final signature. The test thus works mainly for
documenting this feature.

documentation/test_python/pybind_external_overload_docs/docs.rst patch | blob | history
documentation/test_python/pybind_external_overload_docs/pybind_external_overload_docs.Class26.html [new file with mode: 0644] patch | blob
documentation/test_python/pybind_external_overload_docs/pybind_external_overload_docs.cpp patch | blob | history
documentation/test_python/pybind_external_overload_docs/pybind_external_overload_docs.html patch | blob | history
documentation/test_python/test_pybind.py patch | blob | history

diff --git a/documentation/test_python/pybind_external_overload_docs/docs.rst b/documentation/test_python/pybind_external_overload_docs/docs.rst
index 242c1c227b8b52409ae3992d74c3d2888f169f7c..2499e017bff82b50f01b2dbfef58c2d6737e62ac 100644 (file)
--- a/documentation/test_python/pybind_external_overload_docs/docs.rst
+++ b/documentation/test_python/pybind_external_overload_docs/docs.rst
@@ -30,6 +30,10 @@
 
     And the fallback matching works there, too.
 
+.. py:function:: pybind_external_overload_docs.Class26.foo(self, a: int, b: float, keyword: str)
+
+    The ``/`` and ``*`` are excluded from matching.
+
 .. py:function:: pybind_external_overload_docs.foo(first: int)
     :param second: But the second argument doesn't exist?!
 
diff --git a/documentation/test_python/pybind_external_overload_docs/pybind_external_overload_docs.Class26.html b/documentation/test_python/pybind_external_overload_docs/pybind_external_overload_docs.Class26.html
new file mode 100644 (file)
index 0000000..2a742e7
--- /dev/null
+++ b/documentation/test_python/pybind_external_overload_docs/pybind_external_overload_docs.Class26.html
@@ -0,0 +1,77 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <title>pybind_external_overload_docs.Class26 | 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="pybind_external_overload_docs.html">pybind_external_overload_docs</a>.<wbr/></span>Class26 <span class="m-thin">class</span>
+        </h1>
+        <p>Pybind 2.6 features</p>
+        <nav class="m-block m-default">
+          <h3>Contents</h3>
+          <ul>
+            <li>
+              Reference
+              <ul>
+                <li><a href="#methods">Methods</a></li>
+                <li><a href="#data">Data</a></li>
+              </ul>
+            </li>
+          </ul>
+        </nav>
+        <section id="methods">
+          <h2><a href="#methods">Methods</a></h2>
+          <dl class="m-doc">
+            <dt>
+              <span class="m-doc-wrap-bumper">def <a href="#foo" class="m-doc">foo</a>(</span><span class="m-doc-wrap">self,
+              a: int<span class="m-text m-dim">, /</span>,
+              b: float,<span class="m-text m-dim"> *,</span>
+              keyword: str) -&gt; None</span>
+            </dt>
+            <dd>Positional and keyword-only arguments</dd>
+          </dl>
+        </section>
+        <section id="data">
+          <h2><a href="#data">Data</a></h2>
+          <dl class="m-doc">
+            <dt id="is_pybind26">
+              <a href="#is_pybind26" class="m-doc-self">is_pybind26</a> = True
+            </dt>
+            <dd></dd>
+          </dl>
+        </section>
+        <section>
+          <h2>Method documentation</h2>
+          <section class="m-doc-details" id="foo"><div>
+            <h3>
+              <span class="m-doc-wrap-bumper">def pybind_external_overload_docs.<wbr />Class26.<wbr /></span><span class="m-doc-wrap"><span class="m-doc-wrap-bumper"><a href="#foo" class="m-doc-self">foo</a>(</span><span class="m-doc-wrap">self,
+              a: int<span class="m-text m-dim">, /</span>,
+              b: float,<span class="m-text m-dim"> *,</span>
+              keyword: str) -&gt; None</span></span>
+            </h3>
+            <p>Positional and keyword-only arguments</p>
+<p>The <code>/</code> and <code>*</code> are excluded from matching.</p>
+          </div></section>
+        </section>
+      </div>
+    </div>
+  </div>
+</article></main>
+</body>
+</html>
diff --git a/documentation/test_python/pybind_external_overload_docs/pybind_external_overload_docs.cpp b/documentation/test_python/pybind_external_overload_docs/pybind_external_overload_docs.cpp
index e5e8260a0b52f0bab49723871ecbb123cb6c3d7d..59415962403a40ae07bb4d6ca82df37eb26d510a 100644 (file)
--- a/documentation/test_python/pybind_external_overload_docs/pybind_external_overload_docs.cpp
+++ b/documentation/test_python/pybind_external_overload_docs/pybind_external_overload_docs.cpp
@@ -15,6 +15,11 @@ struct Class {
     void foo2(std::string) {}
 };
 
+struct Class26 {
+    void foo1(int) {}
+    void foo2(int, float, const std::string&) {}
+};
+
 PYBIND11_MODULE(pybind_external_overload_docs, m) {
     m.doc() = "pybind11 external overload docs";
 
@@ -28,4 +33,21 @@ PYBIND11_MODULE(pybind_external_overload_docs, m) {
     py::class_<Class>(m, "Class", "My fun class!")
         .def("foo", &Class::foo1, "First overload", py::arg("index"))
         .def("foo", &Class::foo2, "Second overload", py::arg("name"));
+
+    py::class_<Class26> pybind26{m, "Class26", "Pybind 2.6 features"};
+
+    /* Checker so the Python side can detect if testing pybind 2.6 features is
+       feasible */
+    pybind26.attr("is_pybind26") =
+        #if PYBIND11_VERSION_MAJOR*100 + PYBIND11_VERSION_MINOR >= 206
+        true
+        #else
+        false
+        #endif
+        ;
+
+    #if PYBIND11_VERSION_MAJOR*100 + PYBIND11_VERSION_MINOR >= 206
+    pybind26
+        .def("foo", &Class26::foo2, "Positional and keyword-only arguments", py::arg("a"), py::pos_only{}, py::arg("b"), py::kw_only{}, py::arg("keyword"));
+    #endif
 }
diff --git a/documentation/test_python/pybind_external_overload_docs/pybind_external_overload_docs.html b/documentation/test_python/pybind_external_overload_docs/pybind_external_overload_docs.html
index 2766849cd571b0badc90dadc8d39c93bb8fd4d1e..f0f5411005908c2779b21009107294e3c5586e4e 100644 (file)
--- a/documentation/test_python/pybind_external_overload_docs/pybind_external_overload_docs.html
+++ b/documentation/test_python/pybind_external_overload_docs/pybind_external_overload_docs.html
@@ -40,6 +40,8 @@
           <dl class="m-doc">
             <dt>class <a href="pybind_external_overload_docs.Class.html" class="m-doc">Class</a></dt>
             <dd>My fun class!</dd>
+            <dt>class <a href="pybind_external_overload_docs.Class26.html" class="m-doc">Class26</a></dt>
+            <dd>Pybind 2.6 features</dd>
           </dl>
         </section>
         <section id="functions">
diff --git a/documentation/test_python/test_pybind.py b/documentation/test_python/test_pybind.py
index 2905aa61a8b6e48e04cceb3fdc38a518370c5985..3865d97c8d7d4c16535edbd9a565da1819a2ee5c 100644 (file)
--- a/documentation/test_python/test_pybind.py
+++ b/documentation/test_python/test_pybind.py
@@ -419,3 +419,8 @@ class ExternalOverloadDocs(BaseInspectTestCase):
         })
         self.assertEqual(*self.actual_expected_contents('pybind_external_overload_docs.html'))
         self.assertEqual(*self.actual_expected_contents('pybind_external_overload_docs.Class.html'))
+
+        sys.path.append(self.path)
+        import pybind_external_overload_docs
+        if pybind_external_overload_docs.Class26.is_pybind26:
+            self.assertEqual(*self.actual_expected_contents('pybind_external_overload_docs.Class26.html'))
Colin Watson's blog