Merge pull request #170 from OpenMS/upd/docstrings

Update docstrings for overloads in pyx using autodoc syntax.

CHANGELOG.md

@@ -1 +1,3 @@
 autowrap 0.22.10
+
+- Revamped docstrings for overloaded methods in generated pyx files. They use RST and sphinx.autodoc syntax now.

autowrap/CodeGenerator.py

@@ -931,24 +931,28 @@ def _create_overloaded_method_decl(
             # Add autodoc docstring signatures first: https://github.com/sphinx-doc/sphinx/pull/7748
             sig = f"{py_name}(self, {args_typestub_str}) {return_type}"
             signatures.append(sig)
-            docstrings.add(sig)
+            #docstrings.add(sig)
 
-        docstrings.add("")
+        #docstrings.add("")
 
         for method, sig in zip(methods, signatures):
+            docstrings.add(".. rubric:: Overload:")
+            docstrings.add(".. py:function:: %s" % sig)
+            docstrings.add("  :noindex:")
+            docstrings.add("")
             # Now add Cython signatures with additional description for each overload (if available)
             extra_doc = method.cpp_decl.annotations.get("wrap-doc", None)
             if extra_doc is not None:
-                docstrings.add("- Overload: %s" % sig)
-                docstrings.add(extra_doc)
-            docstrings.add("")
+                docstrings.extend(extra_doc)
+                docstrings.add("")
 
         docstring_as_str = docstrings.render(indent=8)
         method_code.add(
             """
                           |
                           |def $py_name(self, *args $kwargs):
                           |    \"\"\"\n$docstring_as_str
+                          |    
                           |    \"\"\"
                         """,
             locals(),

tests/test_code_generator_libcpp.py

@@ -108,7 +108,7 @@ def test_libcpp():
     )
     assert libcpp.__name__ == "libcpp"
     print(dir(libcpp))
-    assert len(libcpp.LibCppTest.__doc__) == 213
+    assert len(libcpp.LibCppTest.__doc__) == 214
     assert len(libcpp.LibCppTest.twist.__doc__) == 111
     assert len(libcpp.LibCppTest.gett.__doc__) == 72
     assert len(libcpp.ABS_Impl1.__doc__) == 90

tests/test_code_generator_minimal.py

@@ -93,7 +93,7 @@ def output_conversion(self, cpp_type, input_cpp_var, output_py_var):
 
     minimal = wrapped.Minimal()
 
-    assert len(minimal.compute.__doc__) == 536
+    assert len(minimal.compute.__doc__) == 681
 
     assert len(minimal.run.__doc__) == 143
 

tests/test_files/inherited.pyx

@@ -1,4 +1,4 @@
-#Generated with autowrap 0.22.9 and Cython (Parser) 0.29.32
+#Generated with autowrap 0.22.10 and Cython (Parser) 0.29.32
 #cython: c_string_encoding=ascii
 #cython: embedsignature=False
 from  enum             import Enum as _PyEnum

tests/test_full_library.py

@@ -291,7 +291,7 @@ def test_full_lib(tmpdir):
     # Check doc string
     assert "Inherits from" in moduleB.Bklass.__doc__
     assert "some doc!" in moduleB.Bklass.__doc__
-    assert len(moduleB.Bklass.__doc__) == 92, len(moduleB.Bklass.__doc__)
+    assert len(moduleB.Bklass.__doc__) == 93, len(moduleB.Bklass.__doc__)
 
     Bsecond = moduleB.B_second(8)
     Dsecond = moduleCD.D_second(11)