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
Nobody has claimed this yet.
- 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
-
OS: Linux and Win
-
Python version: any
-
Sphinx version: 3.1.0
-
Sphinx extensions: in
conf.pyabove -
Extra tools: -
-
https://travis-ci.org/github/microsoft/LightGBM/jobs/696395266#L634
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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