Skip to content

Incorrect documentation for how to enable napoleon extension's napoleon_type_aliases setting #10963

Open
@kbattocchi

Description

@kbattocchi

Describe the bug

The documentation at https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#confval-napoleon_type_aliases incorrectly states that napoleon_use_param must be set to True for napoleon_type_aliases to work:

.. confval:: napoleon_type_aliases
A mapping to translate type names to other names or references. Works
only when ``napoleon_use_param = True``. *Defaults to None.*

Contrast with the extension's own docstring, which correctly notes that it is actually napoleon_preprocess_types that must be True:

napoleon_type_aliases : :obj:`dict` (Defaults to None)
Add a mapping of strings to string, translating types in numpy
style docstrings. Only works if ``napoleon_preprocess_types = True``.

How to Reproduce

Enable a set of aliases in napoleon_type_aliases and set napoleon_use_param = True; those aliases will not be used. If napoleon_preprocess_types is set to True instead then the aliases will be used correctly.

Environment Information

Platform: win32; (Windows-10-10.0.22621-SP0) Python version: 3.9.13 (tags/v3.9.13:6de2ca5, May 17 2022, 16:36:42) [MSC v.1929 64 bit (AMD64)]) Python implementation: CPython Sphinx version: 5.3.0 Docutils version: 0.17.1 Jinja2 version: 3.1.2

Sphinx extensions

["sphinx.ext.autodoc", "sphinx.ext.napoleon"]

Additional context

No response

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions