sphinx-doc / sphinx-doc/sphinx

regression in 3.1.0: docstring of ...:1:duplicate object description of ..., other instance in ..., use :noindex: for one of them

Open
#7,817 13 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

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

Description

Describe the bug
Incompatibility with numpy docstring convention.

Attributes that are properties and have their own docstrings can be simply listed by name:
https://numpydoc.readthedocs.io/en/latest/format.html#class-docstring

To Reproduce
Toy example:

conf.py:

import os
import sys
import sphinx


CURR_PATH = os.path.abspath(os.path.dirname(__file__))
LIB_PATH = os.path.join(CURR_PATH, os.path.pardir, 'python-package')
sys.path.insert(0, LIB_PATH)


# -- General configuration ------------------------------------------------

# The master toctree document.
master_doc = 'index'

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This patterns also effect to html_static_path and html_extra_path
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.autosummary',
    'sphinx.ext.todo',
    'sphinx.ext.viewcode',
    'sphinx.ext.napoleon',
]

autodoc_default_flags = ['members', 'inherited-members', 'show-inheritance']
autodoc_default_options = {
    "members": True,
    "inherited-members": True,
    "show-inheritance": True,
}

# Generate autosummary pages. Output should be set with: `:toctree: pythonapi/`
autosummary_generate = ['Python-API.rst']

# Only the class' docstring is inserted.
autoclass_content = 'class'

# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False

index.rst:

.. toctree::
   :caption: Contents:

   Python API <Python-API>

Python-API.rst:

Python API
==========

.. currentmodule:: lightgbm


Scikit-learn API
----------------

.. autosummary::
    :toctree: pythonapi/

    A

..\python-package\lightgbm\sklearn.py:

class A(object):
    """Class A."""

    def __init__(self, x=42):
        """Init description.

        Parameters
        ----------
        x : int, optional (default=42)
            X description.

        Attributes
        ----------
        n_features_
        classes_ : array of shape = [n_classes]
            The class label array (only for classification problem).
        """
        self.x = x
        self._n_features = None
        self._n_classes = None


    @property
    def n_features_(self):
        """N features description."""
        return self._n_features

    @property
    def classes_(self):
        return 42

Expected behavior
No warnings.

Your project
https://github.com/microsoft/LightGBM/blob/master/docs/conf.py

Environment info

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

Start by reproducing the warning with the minimal conf.py, Python-API.rst, and sklearn.py example, using the listed autodoc, autosummary, and napoleon extensions. Trace how the class and its property docstrings are collected, then verify that the documented attributes no longer produce duplicate-object warnings while the property documentation remains available.

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.