"duplicate object description" warning when Python class has type annotation

[mezhaka]

A Python class with type annotation produces a warning: WARNING: duplicate object description during the sphinx-build if the sphinx.ext.napoleon extension is used. This used to not produce any warnings on version 1.8.5 of sphinx, but produces the warnings in version 3.4.3.

To Reproduce
Steps to reproduce the behavior:

#!/usr/bin/env bash
set -e
set -x

mkdir repro && cd repro
mkdir -p docs/source


cat << EOF > generate_warning.py
class Test:
    """
    Attributes:
        attr: a doc
    """

    attr: bool
EOF


cat << EOF > docs/source/conf.py
import os
import sys
sys.path.insert(0, os.path.abspath('../../'))

extensions = [
    'sphinx.ext.napoleon',
]

source_suffix = '.rst'

# The master toctree document.
master_doc = 'index'
EOF


cat << EOF > docs/source/index.rst
.. toctree::

   apidoc/modules
EOF

# I use conda to create environemnts, but if you don't create a virtual env with
# sphinx 3.4.3 instead of the following block
cat << EOF > environment.yml
name: sphinx-duplicate-warning
channels:
  - conda-forge
  - nodefaults

dependencies:
  - sphinx==3.4.3
EOF

conda env create

Then activate the environment and run sphinx build:

cd repro
conda activate sphinx-duplicate-warning

sphinx-apidoc --force --separate -o docs/source/apidoc . && sphinx-build -M html "docs/source" "build"

Expected behavior
No warning

Your project
repro.zip

Environment info

• OS: MacOS 10.15.7
• Python version: 3.8.6
• Sphinx version: 3.4.3
• Sphinx extensions: sphinx.ext.napoleon

Additional context
Submitted the same report to napoleon repo: sphinx-contrib/napoleon#30

[tk0miya]

Now sphinx-apidoc generates a document for instance variables even not having docstrings (internally, it sets :undoc-members: option by default). Could you set the environment variable SPHINX_APIDOC_OPTIONS=members,show-inheritance before running sphinx-apidoc? Then the entry for Test.attr is not automatically generated.

[mezhaka]

@tk0miya Thank you! This works!

I have a methodological question -- what was your mental process to figure this out?

It seems in order to understand what was the problem I need to know the stages / sequence of document generation -- is there a document that describes it?

[tk0miya]

The answer is reading code, reading code, and reading code :-p

In this case, I passed -vv option to sphinx-build commands to investigate what reST code was generated to your example. And I saw the entries for Test.attr are defined twice (one is generated from docstring of Test class, and another one is from type annotated attribute itself).

[ailin-nemui]

hi @tk0miya is this a bug in napoleon? What if I want undoc members as well as doc members with type annotations? Shouldn't these 2 parts just merge without warning?

[tk0miya]

I think this might be a limitation of napoleon or autodoc. And there is no workaround for the behavior.

These extensions generates the following document internally from above Test class:

.. py:class Test:

   .. py:attribute: attr

      a doc

   .. py:attribute:: attr

After that, two attributes definition causes a warning on building document.
The napoleon simply converts docstring to the reST document. The autodoc is also. So they works as expected. I believe this is not a bug.

Shouldn't these 2 parts just merge without warning?

Please post a PR to resolve it if you find a way!