使用 Python Sphinx 收到警告：myproject 的重复对象描述/使用 :noindex: 对于其中之一

Question

我正在使用 Sphinx 为 Python 项目创建 HTML 文档。

TL;DR 我无法摆脱这个警告消息。

WARNING: duplicate object description of myproject, other instance in class-stubs/Bar, use :noindex: for one of them

我希望索引页看起来像这样：

索引页

项目中的每个类都有一个单独的链接。

我所拥有的实际上有效并给了我想要的结果，但我无法摆脱警告消息。 我见过的有关“重复对象描述”的现有页面都没有给我解决方案。

所有 Python 代码都在一个文件中

myproject.py

。在子目录 class-stubs 中，这三个类中的每一个都有一个单独的 RST 文件。

C:\...\DOCTEST
|   CHANGELOG.rst
|   conf.py
|   index.rst
|   make.bat
|   Makefile
|   myproject.py
|   README.rst
|   setup.py
|
+---class-stubs
        Bar.rst
        Baz.rst
        Foo.rst

myproject.py

中的Python代码是：

"""My Super Python Utility"""

__version__ = "1.2.3.0000"
__all__ = (
    'Foo', 'Bar', 'Baz'
)

class Foo:
    """Foo utilities."""

    @staticmethod
    def spam(filename):
        """Perform the spam operation.
# -[cut]-
        """ 
        return "spam, spam, spam"

class Bar:
    """Bar utilities."""
# -[cut]-

class Baz:
    """Baz utilities."""
# -[cut]-

我们使用 Google 风格的文档字符串和

sphinx.ext.napoleon

扩展。

index.rst如下：

.. My Super Python Project documentation master file

My Super Python Documentation
========================================

Contents:

.. toctree::
   :maxdepth: 1
   
   class-stubs/Foo.rst
   class-stubs/Bar.rst
   class-stubs/Baz.rst
   README.rst
   CHANGELOG.rst
  
Indices and tables
==================

* :ref:`genindex`
* :ref:`search`
~

class-stubs 中的每个类文件的形式类似于

Foo.rst

Foo class
==========

.. automodule:: myproject
   :members: Foo
~

文件

Bar.rst

和

Baz.rst

类似。

使用

make html

编译时，我们会收到以下错误：

Running Sphinx v5.3.0
...
C:\...\doctest\myproject.py:docstring of myproject:1: WARNING: duplicate object description of myproject, other instance in class-stubs/Bar, use :noindex: for one of them
C:\...\doctest\myproject.py:docstring of myproject:1: WARNING: duplicate object description of myproject, other instance in class-stubs/Baz, use :noindex: for one of them

看起来它反对除了第一个类 RST 文件之外的所有文件中的

.. automodule:: myproject

语句。

您可以通过为每个类 RST 文件添加

:noindex:

来删除警告，如下所示

Foo class
==========

.. automodule:: myproject
   :members: Foo
   :noindex:

但这会删除类中方法的 URL 链接，这不是我想要的。

有人可以提出解决方案吗？ （注意：所有类都故意放在一个源代码模块中，因此请不要建议将它们分开。）我应该强调这实际上是有效的，我只是想摆脱那些警告消息。

更新：当然，您可以通过添加到

conf.py

来删除这些消息

suppress_warnings = 'autosectionlabel.*'

但这并不能解决根本问题。

Answer 1

您只能使用

.. automodule:: myproject

对

myproject

模块的引用一次。

因此，如果您多次使用指令

.. automodule::

来引用同一模块，您将收到警告。

警告：我的项目有重复的对象描述

删除其中一项指令。生成相同的自动文档两次是没有用的。或者您的模块可能有不同的名称，那么您也必须使用不同的名称，例如myproject.module2，

myproject.module2

。