如何防止Sphinx在使用槽时在类文档中显示重复的属性？

Question

我正在使用 Sphinx 为 Python 项目生成文档，并且我注意到某些属性在类文档中显示了两次。

这是我当前的简化设置：

job_shop_lib/example_class.py

：

"""An example class to demonstrate the documentation issue."""


class ExampleClass:
    """An example class to demonstrate the documentation issue.

    Attributes:
        attribute1:
            Description of attribute1 from the class docstring.
        attribute2:
            Description of attribute2 from the class docstring.
    """

    __slots__ = ("attribute1", "attribute2")

    def __init__(self):
        self.attribute1 = None
        self.attribute2 = None

这是我的

conf.py

文件：

import os
import sys

sys.path.insert(0, os.path.abspath(".."))

# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

project = "JobShopLib"
copyright = "MIT License"
author = "Pablo Ariño"

# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.napoleon",
    "sphinx.ext.viewcode",
    "sphinx.ext.autosummary",
    "nbsphinx",
    "nbsphinx_link",
    "sphinx.ext.doctest",
    "myst_parser",
    "sphinx.ext.autodoc.typehints",
]

templates_path = ["_templates"]
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "_*.py"]
add_module_names = False
python_use_unqualified_type_names = True
autosummary_generate = True
autosummary_generate_overwrite = True

autodoc_mock_imports = ["ortools"]
autodoc_default_options = {
    "members": True,
    "undoc-members": True,
    "show-inheritance": True,
    "imported-members": False,
    "special-members": "__call__",
    # I tried with no excluded members too
    "exclude-members": "__weakref__, __dict__, __module__, __slots__",
}
add_function_parentheses = True
modindex_common_prefix = ["job_shop_lib."]

autodoc_typehints = "description"
autodoc_typehints_format = "short"

napoleon_include_init_with_doc = True
napoleon_preprocess_types = True

# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

html_theme = "furo"  # pylint: disable=invalid-name
html_static_path = ["_static"]
templates_path = ["_templates"]  # I am not using templates

html_logo = "images/logo_no_bg_resized_fixed.png"

我的

.rst

文件是：

• index.rst

  ：

.. JobShopLib documentation master file, created by
   sphinx-quickstart on Sun Jul  7 16:51:14 2024.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to JobShopLib's documentation!
======================================

**Version:** 1.0.0-alpha.1

A brief description.

Contents
--------

.. toctree::
    :maxdepth: 3

    api

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

• api.rst

  ：

API
===

.. autosummary::
   :toctree: api
   :recursive:

   job_shop_lib

生成的文档显示重复的属性：

显示属性 1 和 2 的图像显示了两次，第一次有描述，第二次没有描述。

如果我从

__slots__

定义中删除属性（即删除行

__slots__ = ("attribute1", "attribute2")

），它们将正确显示：带有描述且没有重复。

Answer 1

作为解决方法，在

__slots__

定义中记录每个属性并删除类文档字符串“属性”部分解决了该问题：

class ExampleClass:
    """An example class to demonstrate the documentation issue."""

    __slots__ = {
        "attribute1": "Description of attribute1 from the class docstring.",
        "attribute2": "Description of attribute2 from the class docstring.",
    }

    def __init__(self):
        self.attribute1 = None
        self.attribute2 = None