docs: document Sphinx autodoc handler for signature * (#4537)

[alisonpetersonhq]

Fixes #4537

Summary

• Keep literal * in generated function signatures (needed by help(), stubgen, and autodoc_docstring_signature).
• Document an autodoc-process-docstring handler in docs/advanced/misc.rst so Sphinx escapes * at doc-build time instead of changing the runtime docstring.

Test plan

• Confirm generated signatures still contain literal *.
• With the documented conf.py handler, Sphinx no longer warns on py::args / py::kw_only signatures.

---

📚 Documentation preview 📚: https://pybind11--6144.org.readthedocs.build/

[henryiii]

I'm not sure this is correct, we'd need to make sure tools like stubgen support this.

This is a standard location for this information so I wonder if there's something sphinx could do (or has a config option for).

[henryiii]

It looks like the standard fix is to add an autodoc-process-docstring event handler in conf.py. The docstrings do need the literal *, that's a Python convention for builtins.

• stubgen
• pybind11-stubgen
• autodoc_docstring_signature (in sphinx)
• help() in Python

[alisonpetersonhq]

Thanks @henryiii — switched approaches.

Kept the literal * in generated signatures (for help() / stubgen / autodoc_docstring_signature), reverted the C++ escape, and documented an autodoc-process-docstring handler in docs/advanced/misc.rst so Sphinx escapes * at doc-build time instead.