英文:
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:
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:
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:
通过集体智慧和协作来改善编程学习和解决问题的方式。致力于成为全球开发者共同参与的知识库,让每个人都能够通过互相帮助和分享经验来进步。
评论