sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.64k stars 2.13k forks source link

Autodoc doesn't honor autodoc_typehints = 'description' for dataclasses #10235

Open Cilyan opened 2 years ago

Cilyan commented 2 years ago

Describe the bug

When documentation for a class decorated with the @dataclass decorator is generated by autodoc, the typehints are written to the class constructor signature, even if autodoc_typehints is set to 'description'.

This does not apply to other classes, even classes that derive from dataclasses, but are not dataclasses themselves.

It seems that the bug only appears if the class has no docstring (TBC).

How to Reproduce

$ git clone https://github.com/Cilyan/sphinx-dataclass-issue
$ cd sphinx-dataclass-issue
$ poetry install
$ cd docs
$ make html
$ # open _build/html/index and see class signatures

Expected behavior

Class signature should not include typehint even for dataclasses, when autodoc_typehints is set to 'description'.

Your project

https://github.com/Cilyan/sphinx-dataclass-issue

Screenshots

First class is dataclass, second class is not a dataclass.

image

OS

Linux 5.16.11-arch1-1 #1 SMP PREEMPT Thu, 24 Feb 2022 02:18:20 +0000 x86_64 GNU/Linux

Python version

3.10.2

Sphinx version

4.4.0

Sphinx extensions

sphinx.ext.autodoc

Extra tools

No response

Additional context

No response

tk0miya commented 2 years ago

This trouble comes from the conflict between autodoc_docstring_signature and autodoc_typehints. autodoc_docstring_signature can forcedly override signature via docstring. It ignores the process of the autodoc_typehints. It would be better to resolve this conflict.

tk0miya commented 2 years ago

As a workaround, you can avoid this problem via 1) setting a docstring to your dataclass, or 2) disable autodoc_docstring_signature feature.

Cilyan commented 2 years ago

Workaround 1 seem the best option in my case, as I need to overload several signatures throughout the code.