mirror of
https://github.com/pybricks/pybricks-api.git
synced 2026-09-11 09:05:07 +00:00
Laurens Valk
9bd82f7246
Use clean upstream Sphinx and use extensions for the awaitable types and work around a Sphinx docstring parsing bug.
52 lines
2.0 KiB
Python
52 lines
2.0 KiB
Python
"""Make explicit docstring signatures win over ``@overload`` signatures.
|
|
|
|
Workaround for https://github.com/sphinx-doc/sphinx/issues/10436: when a
|
|
function or method has overloads, autodoc unconditionally replaces the
|
|
signature(s) found in the docstring with the overload signatures. Classes
|
|
already behave correctly, so this only patches the function/method path. There
|
|
is no event hook for this in autodoc's new (Sphinx 9) pipeline, so
|
|
``_format_signatures`` is wrapped: when a docstring signature is present,
|
|
``autodoc_typehints`` is set to ``'none'`` for that single call, which
|
|
disables only the overload substitution branch.
|
|
"""
|
|
|
|
from sphinx.application import Sphinx
|
|
from sphinx.ext.autodoc._dynamic import _loader, _signatures
|
|
from sphinx.ext.autodoc._shared import _AutodocConfig
|
|
|
|
_orig_format_signatures = _signatures._format_signatures
|
|
|
|
|
|
def _format_signatures(**kwargs):
|
|
config: _AutodocConfig = kwargs["config"]
|
|
docstrings = kwargs.get("docstrings")
|
|
options = kwargs["options"]
|
|
props = kwargs["props"]
|
|
|
|
if (
|
|
kwargs.get("args") is None
|
|
and docstrings
|
|
and config.autodoc_docstring_signature
|
|
and config.autodoc_typehints != "none"
|
|
and props.obj_type in {"function", "method", "decorator"}
|
|
):
|
|
# Probe on a copy: extraction strips signature lines from docstrings.
|
|
docstring_signatures = _signatures._extract_signatures_from_docstrings(
|
|
[list(lines) for lines in docstrings],
|
|
props=props,
|
|
tab_width=options._tab_width,
|
|
)
|
|
if docstring_signatures:
|
|
values = {name: getattr(config, name) for name in _AutodocConfig.__slots__}
|
|
values["autodoc_typehints"] = "none"
|
|
kwargs["config"] = _AutodocConfig(**values)
|
|
|
|
return _orig_format_signatures(**kwargs)
|
|
|
|
|
|
def setup(app: Sphinx):
|
|
_signatures._format_signatures = _format_signatures
|
|
_loader._format_signatures = _format_signatures
|
|
|
|
return {"parallel_read_safe": True}
|