Prepend all function signatures to docstrings and disable headings

AWhetter · rwgk · commit 09b144f25b62 · 2022-01-14T16:27:42.000-08:00
diff --git a/docs/advanced/misc.rst b/docs/advanced/misc.rst
@@ -302,6 +302,106 @@ Note that changes to the settings affect only function bindings created during t
 lifetime of the ``options`` instance. When it goes out of scope at the end of the module's init function,
 the default settings are restored to prevent unwanted side effects.
 
+Overloaded functions
+--------------------
+
+For overloaded functions, a generic function signature is prepended to the
+docstring of a function, and all overload docstrings are concatenated together
+into sections that are separated by each function signature.
+
+For example:
+
+.. code-block:: pycon
+
+    >>> help(example.add)
+
+    add(...)
+     |      add(*args, **kwargs)
+     |      Overloaded function.
+     |
+     |      1. add(arg0: int, arg1: int) -> int
+     |
+     |      Add two integers together.
+     |
+     |      2. add(arg0: float, arg1: float) -> float
+     |
+     |      Add two floating point numbers together.
+
+Calling ``options.enable_prepended_overload_signatures()`` will cause docstrings to be
+prepended with the signature of each overload instead of a generic function signature.
+The prepended signatures can be read by tools like Sphinx.
+
+.. code-block:: cpp
+
+    PYBIND11_MODULE(example, m) {
+        py::options options;
+        options.enable_prepended_overload_signatures();
+
+        m.def("add", [](int a, int b)->int { return a + b; },
+          "Add two integers together.");
+        m.def("add", [](float a, float b)->float { return a + b; },
+          "Add two floating point numbers together.");
+    }
+
+The above example would produce the following docstring:
+
+.. code-block:: pycon
+
+    >>> help(example.add)
+
+    add(...)
+     |      add(arg0: int, arg1: int) -> int
+     |      add(arg0: float, arg1: float) -> float
+     |
+     |      Overloaded function.
+     |
+     |      1. add(arg0: int, arg1: int) -> int
+     |
+     |      Add two integers together.
+     |
+     |      2. add(arg0: float, arg1: float) -> float
+     |
+     |      Add two floating point numbers together.
+
+Calling ``options.disable_function_signatures()`` as shown previously,
+will cause docstrings to be generated without the prepended function signatures
+and without the section headings.
+To disable only the sections headings, use ``options.disable_section_headings()``:
+
+.. code-block:: cpp
+
+    PYBIND11_MODULE(example, m) {
+        py::options options;
+        options.disable_section_headings();
+        options.enable_prepended_overload_signatures();
+
+        m.def("add", [](int a, int b)->int { return a + b; },
+          "A function which adds two numbers.\n");  // Note the additional newline here.
+        m.def("add", [](float a, float b)->float { return a + b; },
+          "Internally, a simple addition is performed.");
+        m.def("add", [](const py::none&, const py::none&)->py::none { return py::none(); },
+          "Both numbers can be None, and None will be returned.");
+    }
+
+The above example would produce the following docstring:
+
+.. code-block:: pycon
+
+    >>> help(example.add)
+
+    add(...)
+     |      add(arg0: int, arg1: int) -> int
+     |      add(arg0: float, arg1: float) -> float
+     |      add(arg0: None, arg1: None) -> None
+     |
+     |      A function which adds two numbers.
+     |
+     |      Internally, a simple addition is performed.
+     |      Both numbers can be None, and None will be returned.
+
+Not every overload must supply a docstring.
+You may find it easier for a single overload to supply the entire docstring.
+
 .. [#f4] http://www.sphinx-doc.org
 .. [#f5] http://github.com/pybind/python_example
 
diff --git a/include/pybind11/options.h b/include/pybind11/options.h
@@ -38,12 +38,24 @@ class options {
 
     options& enable_function_signatures() & { global_state().show_function_signatures = true; return *this; }
 
+    options& disable_section_headings() & { global_state().show_section_headings = false; return *this; }
+
+    options& enable_section_headings() & { global_state().show_section_headings = true; return *this; }
+
+    options& disable_prepended_overload_signatures() & { global_state().prepend_overload_signatures = false; return *this; }
+
+    options& enable_prepended_overload_signatures() & { global_state().prepend_overload_signatures = true; return *this; }
+
     // Getter methods (return the global state):
 
     static bool show_user_defined_docstrings() { return global_state().show_user_defined_docstrings; }
 
     static bool show_function_signatures() { return global_state().show_function_signatures; }
 
+    static bool show_section_headings() { return global_state().show_section_headings; }
+
+    static bool prepend_overload_signatures() { return global_state().prepend_overload_signatures; }
+
     // This type is not meant to be allocated on the heap.
     void* operator new(size_t) = delete;
 
@@ -52,6 +64,8 @@ class options {
     struct state {
         bool show_user_defined_docstrings = true;  //< Include user-supplied texts in docstrings.
         bool show_function_signatures = true;      //< Include auto-generated function signatures in docstrings.
+        bool show_section_headings = true;         //< Include section headings in docstrings.
+        bool prepend_overload_signatures = false;  //< Prepend all signatures of overloads in docstrings.
     };
 
     static state &global_state() {
diff --git a/include/pybind11/pybind11.h b/include/pybind11/pybind11.h
@@ -502,18 +502,32 @@ class cpp_function : public function {
 
         std::string signatures;
         int index = 0;
+        bool first_user_def = true;
         /* Create a nice pydoc rec including all signatures and
            docstrings of the functions in the overload chain */
         if (chain && options::show_function_signatures()) {
-            // First a generic signature
-            signatures += rec->name;
-            signatures += "(*args, **kwargs)\n";
-            signatures += "Overloaded function.\n\n";
+            if (options::prepend_overload_signatures()) {
+                for (auto it = chain_start; it != nullptr; it = it->next) {
+                    signatures += rec->name;
+                    signatures += it->signature;
+                    signatures += "\n";
+                }
+            }
+            else {
+                // Use a single generic signature
+                signatures += rec->name;
+                signatures += "(*args, **kwargs)";
+            }
+            if (options::show_section_headings())
+                signatures += "\nOverloaded function.\n\n";
+            else
+                first_user_def = false;
         }
         // Then specific overload signatures
-        bool first_user_def = true;
+        const bool show_signature_headings = options::show_function_signatures()
+            && options::show_section_headings();
         for (auto it = chain_start; it != nullptr; it = it->next) {
-            if (options::show_function_signatures()) {
+            if (show_signature_headings) {
                 if (index > 0) signatures += "\n";
                 if (chain)
                     signatures += std::to_string(++index) + ". ";
@@ -522,15 +536,14 @@ class cpp_function : public function {
                 signatures += "\n";
             }
             if (it->doc && it->doc[0] != '\0' && options::show_user_defined_docstrings()) {
-                // If we're appending another docstring, and aren't printing function signatures, we
+                // If we're appending another docstring, and aren't printing signature headings, we
                 // need to append a newline first:
-                if (!options::show_function_signatures()) {
-                    if (first_user_def) first_user_def = false;
-                    else signatures += "\n";
-                }
-                if (options::show_function_signatures()) signatures += "\n";
+                if (!show_signature_headings && first_user_def)
+                    first_user_def = false;
+                else
+                    signatures += "\n";
                 signatures += it->doc;
-                if (options::show_function_signatures()) signatures += "\n";
+                if (show_signature_headings) signatures += "\n";
             }
         }
 
diff --git a/tests/test_docstring_options.cpp b/tests/test_docstring_options.cpp
@@ -66,4 +66,32 @@ TEST_SUBMODULE(docstring_options, m) {
             .def_property("value_prop", &DocstringTestFoo::getValue, &DocstringTestFoo::setValue, "This is a property docstring")
         ;
     }
+
+    m.def("test_overloaded4", [](int a, int b)->int { return a + b; },
+        "Add two integers together.");
+    m.def("test_overloaded4", [](float a, float b)->float { return a + b; },
+        "Add two floating point numbers together.");
+
+    {
+        py::options options;
+        options.enable_prepended_overload_signatures();
+
+        m.def("test_overloaded5", [](int a, int b)->int { return a + b; },
+            "Add two integers together.");
+        m.def("test_overloaded5", [](float a, float b)->float { return a + b; },
+            "Add two floating point numbers together.");
+    }
+
+    {
+        py::options options;
+        options.disable_section_headings();
+        options.enable_prepended_overload_signatures();
+
+        m.def("test_overloaded6", [](int a, int b)->int { return a + b; },
+          "A function which adds two numbers.\n");
+        m.def("test_overloaded6", [](float a, float b)->float { return a + b; },
+          "Internally, a simple addition is performed.");
+        m.def("test_overloaded6", [](const py::none&, const py::none&)->py::none { return py::none(); },
+          "Both numbers can be None, and None will be returned.");
+    }
 }
diff --git a/tests/test_docstring_options.py b/tests/test_docstring_options.py
@@ -40,3 +40,43 @@ def test_docstring_options():
     # Suppression of user-defined docstrings for non-function objects
     assert not m.DocstringTestFoo.__doc__
     assert not m.DocstringTestFoo.value_prop.__doc__
+
+    # Check overload configuration behaviour matches the documentation
+    assert m.test_overloaded4.__doc__ == (
+        "test_overloaded4(*args, **kwargs)\n"
+        "Overloaded function.\n"
+        "\n"
+        "1. test_overloaded4(arg0: int, arg1: int) -> int\n"
+        "\n"
+        "Add two integers together.\n"
+        "\n"
+        "2. test_overloaded4(arg0: float, arg1: float) -> float\n"
+        "\n"
+        "Add two floating point numbers together.\n"
+    )
+
+    assert m.test_overloaded5.__doc__ == (
+        "test_overloaded5(arg0: int, arg1: int) -> int\n"
+        "test_overloaded5(arg0: float, arg1: float) -> float\n"
+        "\n"
+        "Overloaded function.\n"
+        "\n"
+        "1. test_overloaded5(arg0: int, arg1: int) -> int\n"
+        "\n"
+        "Add two integers together.\n"
+        "\n"
+        "2. test_overloaded5(arg0: float, arg1: float) -> float\n"
+        "\n"
+        "Add two floating point numbers together.\n"
+    )
+
+    assert m.test_overloaded6.__doc__ == (
+        "test_overloaded6(arg0: int, arg1: int) -> int\n"
+        "test_overloaded6(arg0: float, arg1: float) -> float\n"
+        "test_overloaded6(arg0: None, arg1: None) -> None\n"
+        "\n"
+        "A function which adds two numbers.\n"
+        "\n"
+        "Internally, a simple addition is performed.\n"
+        "Both numbers can be None, and None will be returned."
+    )
