handle overloads (#433)
Build on RHEL9 / build (push) Successful in 3m49s
Build on RHEL8 / build (push) Successful in 4m8s
Run tests using data on local RHEL8 / build (push) Successful in 4m44s
Build on local RHEL8 / build (push) Successful in 3m21s

Pybind11 merges all docstrings of overloaded functions into one
docstring.
Sphinx rendering usually complains about these merged docstrings e.g
unexpected Section titles.

Added a custom sphinx extension that overwrites the standard pybind11
method and function document handler.

The handler splits the pybind generated docstring and adds for each
overload its own method header.
This commit is contained in:
mazzol_a authored and GitHub committed 2026-11-03 09:51:26 +01:00
1 parent 7abbf3cbb5
commit 56e880638e
3 files changed
+154 -28

No files matched your search

+5 -24
View File
@@ -11,32 +11,13 @@ configure_file(${DOXYGEN_IN} ${DOXYGEN_OUT} @ONLY)
set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR}/src)
set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR})
file(
GLOB_RECURSE SPHINX_SOURCE_FILES CONFIGURE_DEPENDS
RELATIVE "${CMAKE_CURRENT_SOURCE_DIR}/src"
"${CMAKE_CURRENT_SOURCE_DIR}/src/*.rst")
foreach(relpath IN LISTS SPHINX_SOURCE_FILES)
set(src "${CMAKE_CURRENT_SOURCE_DIR}/src/${relpath}")
set(dst "${SPHINX_BUILD}/src/${relpath}")
message(STATUS "Copying ${src} to ${dst}")
configure_file("${src}" "${dst}" COPYONLY)
endforeach()
configure_file("${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in"
"${SPHINX_BUILD}/conf.py" @ONLY)
file(COPY "${CMAKE_CURRENT_SOURCE_DIR}/figures" DESTINATION "${SPHINX_BUILD}")
configure_file("${CMAKE_CURRENT_SOURCE_DIR}/static/extra.css"
"${SPHINX_BUILD}/static/css/extra.css" @ONLY)
add_custom_target(
docs
COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_OUT}
COMMAND
${SPHINX_EXECUTABLE} -W -a -b html
-Dbreathe_projects.aare=${CMAKE_CURRENT_BINARY_DIR}/xml -c "${SPHINX_BUILD}"
${SPHINX_BUILD}/src ${SPHINX_BUILD}/html
${CMAKE_COMMAND} -E env "PYTHONPATH=${CMAKE_BINARY_DIR}" # find aare module
${SPHINX_EXECUTABLE} -W -a -b html -Dversion=${PROJECT_VERSION}
-Drelease=${PROJECT_VERSION}
-Dbreathe_projects.aare=${CMAKE_CURRENT_BINARY_DIR}/xml -c
"${CMAKE_CURRENT_SOURCE_DIR}" ${SPHINX_SOURCE} ${SPHINX_BUILD}/html
COMMENT "Generating documentation with Sphinx")
+5 -4
View File
@@ -13,9 +13,8 @@
#
import os
import sys
sys.path.insert(0, os.path.abspath('..'))
sys.path.insert(0, os.path.abspath(os.path.dirname(__file__))) # finds pybind_overloads.py
print(sys.path)
# -- Project information -----------------------------------------------------
@@ -23,6 +22,7 @@ project = 'aare'
copyright = '2024, CPS Detector Group'
author = 'CPS Detector Group'
version = '@PROJECT_VERSION@'
release = '@PROJECT_VERSION@'
# -- General configuration ---------------------------------------------------
@@ -32,10 +32,12 @@ version = '@PROJECT_VERSION@'
extensions = ['breathe',
'sphinx.ext.autodoc',
'sphinx.ext.napoleon',
'pybind_overloads',
]
breathe_default_project = "aare"
napoleon_use_ivar = True
napoleon_numpy_docstring = True
# Add any paths that contain templates here, relative to this directory.
@@ -59,6 +61,5 @@ html_theme = "furo"
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['static']
def setup(app):
app.add_css_file('css/extra.css') # may also be an URL
app.add_css_file('extra.css') # relative to _static/; may also be an URL
+144
View File
@@ -0,0 +1,144 @@
# SPDX-License-Identifier: MPL-2.0
"""Sphinx extension that documents pybind11 overloads as separate entries.
pybind11 merges the docstrings of all overloads of a function into one::
name(*args, **kwargs)
Overloaded function.
1. name(self: pkg.Cls, a: int) -> int
docstring of overload 1
2. name(self: pkg.Cls, a: float) -> float
docstring of overload 2
This extension replaces autodoc's function and method documenters so that
every overload is rendered as its own entry, with its own signature and
docstring, as if it were a separate function::
name(a: int) -> int
docstring of overload 1
name(a: float) -> float
docstring of overload 2
Every overload body goes through ``autodoc-process-docstring`` on its own, so
napoleon renders the ``Parameters``/``Returns`` sections of each overload.
Works for any overloaded function, method, operator or ``__call__``.
"""
import re
import textwrap
from sphinx.ext.autodoc import FunctionDocumenter, MethodDocumenter
from sphinx.util.docstrings import prepare_docstring
OVERLOAD_MARKER = "Overloaded function."
# "1. name(args) -> ret"; args may contain nested parentheses (default values),
# so match greedily up to the last ")" before an optional "-> ret".
_HEADER_RE = re.compile(
r"^(?P<idx>\d+)\.\s+(?P<name>[\w.]+)\((?P<args>.*)\)\s*(?:->\s*(?P<ret>.+?))?\s*$"
)
# Leading "self" / "self: pkg.Cls" argument of a bound method
_SELF_RE = re.compile(r"^\s*self(?:\s*:\s*[^,]+)?\s*(?:,\s*|$)")
# Fully qualified dotted names, e.g. aare._aare.ROI or numpy.typing.NDArray
#_QUALIFIED_RE = re.compile(r"\b(?:[A-Za-z_]\w*\.)+([A-Za-z_]\w*)")
def _split_overloads(lines):
"""Return [(header_match, body_lines), ...] or None if not overloaded."""
try:
start = next(i for i, l in enumerate(lines) if l.strip() == OVERLOAD_MARKER)
except StopIteration:
return None
# Everything before the marker must be blank or the "name(*args, **kwargs)" line
if any(l.strip() and not l.strip().endswith("(*args, **kwargs)") for l in lines[:start]):
return None
overloads = []
func_name = None
for line in lines[start + 1:]:
m = _HEADER_RE.match(line)
# Only accept "N. name(" at column 0 with the expected index and the same
# name, so numbered lists inside a docstring are not mistaken for headers.
if (m and int(m["idx"]) == len(overloads) + 1
and func_name in (None, m["name"])):
func_name = m["name"]
overloads.append((m, []))
elif overloads:
overloads[-1][1].append(line)
return overloads or None
class PybindOverloadMixin:
"""Render each pybind11 overload as a separate directive.
The first overload uses the directive autodoc generates anyway; the others
are appended as sibling directives (with ``:no-index:`` to avoid duplicate
object warnings) after the first overload's content.
"""
_overloads = None
_current = 0
def format_signature(self, **kwargs):
doc = getattr(self.object, "__doc__", None)
self._overloads = _split_overloads(prepare_docstring(doc)) if isinstance(doc, str) else None
if not self._overloads:
return super().format_signature(**kwargs)
return self._overload_signature(0)
def get_doc(self):
if not self._overloads:
return super().get_doc()
body = self._overloads[self._current][1]
return [prepare_docstring(textwrap.dedent("\n".join(body)))]
def add_content(self, more_content):
super().add_content(more_content)
if not self._overloads or self._current:
return
sourcename = self.get_sourcename()
content_indent = self.indent
outer_indent = content_indent[: len(content_indent) - len(self.content_indent)]
for i in range(1, len(self._overloads)):
self._current = i
self.indent = outer_indent
self.add_line("", sourcename)
self.add_directive_header(self._overload_signature(i))
if not (self.options.no_index or self.options.noindex):
self.add_line(" :no-index:", sourcename)
self.add_line("", sourcename)
self.indent = content_indent
super().add_content(None)
self._current = 0
def _overload_signature(self, i):
header = self._overloads[i][0]
sig = f"({_SELF_RE.sub('', header['args'], count=1)})"
if header["ret"]:
sig += f" -> {header['ret']}"
return sig
class PybindFunctionDocumenter(PybindOverloadMixin, FunctionDocumenter):
pass
class PybindMethodDocumenter(PybindOverloadMixin, MethodDocumenter):
pass
def setup(app):
app.setup_extension("sphinx.ext.autodoc")
#app.add_config_value("pybind_overloads_short_names", False, "env") # not sure if needed
app.add_autodocumenter(PybindFunctionDocumenter, override=True) # overwrites existing pybind autodoc function documenter
app.add_autodocumenter(PybindMethodDocumenter, override=True)
return {"parallel_read_safe": True, "parallel_write_safe": True} # extension metadata