pythonpython-sphinxautodoc

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.


Solution

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