Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Make autodoc_typehints="description" work with autoclass_content="class" #8539

Merged
merged 3 commits into from Apr 3, 2021
Merged

Make autodoc_typehints="description" work with autoclass_content="class" #8539

merged 3 commits into from Apr 3, 2021

Commits on Mar 27, 2021

  1. Add autodoc_typehint_undoc option 

    Previously, if autodoc_typehints="description", a :type: field would be
added for every parameter and return type appearing in the annotation,
including **kwargs and underscore-prefixed parameters that are meant to
be private, as well as None return types.

This commit introduces a new option, "autodoc_typehint_undoc".  By
default this option is True, requesting the old behavior. By setting
this option to False, :type: and :rtype: fields will only be added for
annotated parameters or return types if there is already a corresponding
:param: or :return: field, to put users in control over whether a given
parameter is documented or not.
    @godlygeek
    godlygeek committed Mar 27, 2021
    Copy the full SHA
    4785f32 View commit details
    Browse the repository at this point in the history

  2. Use __init__ type hints in "description" mode 

    Previously, `__init__` type hints were not used when documenting a class
using `autodoc_typehints="description"`. This was done to prevent
documentation for parameters from showing up twice, both for the class
and the `__init__` special method. As the new ``autodoc_typehint_undoc``
option provides a better way to prevent this bad behavior by placing the
user in control of where the type hints are added, it is now safe to add
type hints for documented `__init__` parameters.

Closes sphinx-doc#8178
    @godlygeek
    godlygeek committed Mar 27, 2021
    Copy the full SHA
    be2cee5 View commit details
    Browse the repository at this point in the history

  3. Test autodoc_typehint_undoc 

    Add new tests to exercise the new autodoc_typehint_undoc option. Where
an existing test would have a meaningful behavior change with the new
option set to False, that test is copied, the new option is set to False
in the copy, and the assertions reflect the new expected behavior.

The new test test_autodoc_typehints_description_with_documented_init
illustrates the problem reported in sphinx-doc#7329, and the new test
test_autodoc_typehints_description_with_documented_init_no_undoc
illustrates that this issue no longer occurs when the new
autodoc_typehint_undoc option is set to False.
    @godlygeek
    godlygeek committed Mar 27, 2021
    Copy the full SHA
    4c72848 View commit details
    Browse the repository at this point in the history