“使用Python Sphinx获取警告:myproject的对象描述重复/使用:noindex:中的一个。”

huangapple go评论63阅读模式
英文:

Using Python Sphinx getting WARNING: duplicate object description of myproject / use :noindex: for one of them

问题

I'm using Sphinx to create HTML documentation for a Python project.

TL;DR I cannot get rid of this warning message.

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

I want the index page to look like this:

Index page

with a separate link for each class in the project.

What I have actually works and gives me the result I want, but I cannot get rid of the warning messages.
None of the existing pages I've seen about the "duplicate object description" give me a solution.

All the Python code is in one file myproject.py. There is a separate RST file for each of the three classes in the subdirectory class-stubs.

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

The Python code in myproject.py is:

"""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]-

We use Google style docstrings and the sphinx.ext.napoleon extension.

index.rst is as follows:

.. 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`
~

Each class file in class-stubs is of the form similar to Foo.rst

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

.. automodule:: myproject
   :members: Foo
~

The files Bar.rst and Baz.rst are similar.

On compiling with make html we get these errors:

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

It looks like it is objecting to the .. automodule:: myproject statement in all but the first of the class RST files.

You can remove the warnings by adding :noindex: for each class RST file like this

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

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

but this removes the URL links to the methods in the class, which is not what I want.

Can anyone suggest a solution? (NOTE: all the classes are deliberately in the one source code module, so please do not suggest separating them.) I should emphasise that this actually works, I just want to get rid of those warning messages.

UPDATE: of course you get rid of those messages by adding to conf.py

suppress_warnings = 'autosectionlabel.*'

but that doesn't solve the underlying problem.

UPDATE: @mzjn Change automodule to autoclass in each of the stub files like this:

Bar class
============

.. autoclass:: myproject
   :members: Bar

This gives a warning:

WARNING: don't know which module to import for autodocumenting 
'myproject' (try placing a "module" or "currentmodule" directive in 
the document, or giving an explicit module name)

and the page for each class just has the title but no content.

If I set just one of the classes to have automodule (eg Bar.rst) and the other two with autoclass, then there is no warning and the Bar page is correct BUT the other class pages have no content.

英文:

I'm using Sphinx to create HTML documentation for a Python project.

TL;DR I cannot get rid of this warning message.

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

I want the index page to look like this:

Index page

with a separate link for each class in the project.

What I have actually works and gives me the result I want, but I cannot get rid of the warning messages.
None of the existing pages I've seen about the "duplicate object description" give me a solution.

All the Python code is in one file myproject.py. There is a separate RST file for each of the three classes in the subdirectory class-stubs.

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

The Python code in myproject.py is:

"""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]-

We use Google style docstrings and the sphinx.ext.napoleon extension.

index.rst is as follows:

.. 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`
~

Each class file in class-stubs is of the form similar to Foo.rst

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

.. automodule:: myproject
   :members: Foo
~

The files Bar.rst and Baz.rst are similar.

On compiling with make html we get these errors:

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

It looks like it is objecting to the .. automodule:: myproject statement in all but the first of the class RST files.

You can remove the warnings by adding :noindex: for each class RST file like this

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

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

but this removes the URL links to the methods in the class, which is not what I want.

Can anyone suggest a solution? (NOTE: all the classes are deliberately in the one source code module, so please do not suggest separating them.) I should emphasise that this actually works, I just want to get rid of those warning messages.

UPDATE: of course you get rid of those messages by adding to conf.py

suppress_warnings = 'autosectionlabel.*'

but that doesn't solve the underlying problem.

UPDATE: @mzjn Change automodule to autoclass in each of the stub files like this:

Bar class
============

.. autoclass:: myproject
   :members: Bar

This gives a warning:

WARNING: don't know which module to import for autodocumenting 
'myproject' (try placing a "module" or "currentmodule" directive in 
the document, or giving an explicit module name)

and the page for each class just has the title but no content.

If I set just one of the classes to have automodule (eg Bar.rst) and the other two with autoclass, then there is no warning and the Bar page is correct BUT the other class pages have no content.

答案1

得分: 1

你可以使用 .. automodule:: myproject 引用 myproject 模块,但只能使用一次。

因此,如果你多次使用 .. automodule:: 指令引用相同的模块,将会收到警告。

> 警告:重复的对象描述

请删除其中一个相同的指令。生成相同的自动文档两次是没有意义的。

或者,可能你的模块有不同的名称,那么你必须使用不同的名称,例如 .. automodule:: myproject.module1.. automodule:: myproject.module2

英文:

You can use the .. automodule:: myproject reference to myproject module only once.

Therefore if you use directive .. automodule:: with reference to the same module multiple times, you will get the warning.

> WARNING: duplicate object description

Delete one of the identical directives. There is no use to generate the same autodoc two times.

Or, possibly, your modules have different names, then you must also use different names, e.g. .. automodule:: myproject.module1 and .. automodule:: myproject.module2.

答案2

得分: 1

只有一个模块,但你使用了 automodule 指令三次。这就是你收到警告的原因。

相反,你可以为每个类使用 autoclass。对于 Foo 类,它会像这样:

Foo class
=========

.. autoclass:: myproject.Foo
   :members:
英文:

There is only one module, but you use the automodule directive three times. That is why you get the warnings.

Instead, you can use autoclass for each class. It would look like this for the Foo class:

Foo class
=========

.. autoclass:: myproject.Foo
   :members:

huangapple
  • 本文由 发表于 2023年5月21日 20:26:55
  • 转载请务必保留本文链接:https://go.coder-hub.com/76299903.html
匿名

发表评论

匿名网友

:?: :razz: :sad: :evil: :!: :smile: :oops: :grin: :eek: :shock: :???: :cool: :lol: :mad: :twisted: :roll: :wink: :idea: :arrow: :neutral: :cry: :mrgreen:

确定