sphinx-doc / sphinx-doc/sphinx

Impossible to properly document NamedTuple with attribute annotations

Open
#8,717 1 comment 3 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

type:bug
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

It's not possible to properly document NamedTuple with autodoc.

test.rst:

test module
===========

.. automodule:: test
   :members:
   :undoc-members:
   :show-inheritance:

test.py:

from typing import NamedTuple

class Foo(NamedTuple):
    """Description

    Attributes:
        foo: This shows the type properly, but gives a warning
    """

    foo: float

    bar: str # This doesn't show the type

    baz: int #: This also doesn't show the type

Results in:
Screenshot 2021-01-21 at 09 29 32

and the error:

test.py:docstring of test.Foo.foo:1: WARNING: duplicate object description of test.Foo.foo, other instance in source/test, use :noindex: for one of them
  1. foo: Documenting foo in Attributes and adding the type below (which is the preferred way of documenting this) results in a duplicate entry in the documentation as well as the duplicate object description error.
  2. bar: Not documenting it shows neither type nor description
  3. baz: Adding the description in an inline comment shows the description, but ignores the type of the variable.

Expected
I would expect 1) to remove the duplicate entry, and 2) and 3) to show the proper type automatically in the documentation.

Environment info

  • OS: Mac
  • Python version: [e.g. 3.7.1]
  • Sphinx version: 3.4.3
  • Sphinx extensions: "sphinx.ext.autodoc", "sphinx.ext.napoleon",
  • napoleon_attr_annotations = True

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Reproduce the report with test.rst and test.py using Sphinx 3.4.3, autodoc, napoleon, and napoleon_attr_annotations enabled. Start by tracing how autodoc renders the NamedTuple attributes and their annotations; done means the foo duplicate warning is removed and bar and baz show their types and descriptions as expected.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.