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.
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: