Sphinx: What is the cause for 'WARNING: duplicate object description'?

Question

I am getting multiple warnings like:

WARNING: duplicate object description of pyfar.signal.TimeData.times, other instance in pyfar.classes_audio, use :noindex: for one of them

but can not figure out why? Someone suggested that I probably include the same object twice in different rst files. But I don't think this is the case.

I tried to create a minimal working example based on the original package (https://github.com/pyfar/pyfar/tree/develop/docs):

Get the code

git clone https://github.com/f-brinkmann/pyfar_sphinx_test.git pyfar_sphinx_test
cd pyfar_sphinx_test

Make a virtual environment

conda create --name sphinx_test python<3.9
conda activate sphinx_test
pip install -r requirements_dev.txt
pip install -e .

Building the documentation

cd docs
make clean
make html

Yields

Running Sphinx v3.5.3
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: [new config] 1 added, 0 changed, 0 removed
reading sources... [100%] index
C:\Users\panik\Desktop\pyfar_sphinx_test\pyfar\signal.py:docstring of pyfar.signal.FrequencyData.fft_norm:1: WARNING: duplicate object description of pyfar.signal.FrequencyData.fft_norm, other instance in index, use :noindex: for one of them
C:\Users\panik\Desktop\pyfar_sphinx_test\pyfar\signal.py:docstring of pyfar.signal.FrequencyData.frequencies:1: WARNING: duplicate object description of pyfar.signal.FrequencyData.frequencies, other instance in index, use :noindex: for one of them
C:\Users\panik\Desktop\pyfar_sphinx_test\pyfar\signal.py:docstring of pyfar.signal.Signal.domain:1: WARNING: duplicate object description of pyfar.signal.Signal.domain, other instance in index, use :noindex: for one of them
C:\Users\panik\Desktop\pyfar_sphinx_test\pyfar\signal.py:docstring of pyfar.signal.Signal.fft_norm:1: WARNING: duplicate object description of pyfar.signal.Signal.fft_norm, other instance in index, use :noindex: for one of them
C:\Users\panik\Desktop\pyfar_sphinx_test\pyfar\signal.py:docstring of pyfar.signal.Signal.sampling_rate:1: WARNING: duplicate object description of pyfar.signal.Signal.sampling_rate, other instance in index, use :noindex: for one of them
C:\Users\panik\Desktop\pyfar_sphinx_test\pyfar\signal.py:docstring of pyfar.signal.TimeData.times:1: WARNING: duplicate object description of pyfar.signal.TimeData.times, other instance in index, use :noindex: for one of them
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
generating indices... genindex py-modindex done
highlighting module code... [100%] pyfar.signal
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 6 warnings.

Thanks for any replies, Fabian

Most people on SO probably know nothing about pyfar. Please provide a [mcve]. This question does not contain more information that your other closed question. — mzjn, Mar 31 '21 at 16:20
Sorry @mzjn. I generated a minimal example and steps to reproduce my problem. Thanks for the patience, Fabian — fabian, Apr 01 '21 at 08:54

score 6 · Accepted Answer · answered Apr 01 '21 at 10:35

The problem seems to be that you use the Attributes header in the docstring for some __init__ methods. The warnings go away if that is changed to Parameters (which is the correct header).

Example:

def __init__(self, data, frequencies, fft_norm=None, comment=None,
                 dtype=complex):
        """Init FrequencyData with data, and frequencies.
 
        Parameters
        ----------
        data : array, double
            Raw data in the frequency domain. The memory layout of Data is 'C'.
            E.g. data of shape (3, 2, 1024) has 3 x 2 channels with 1024
            frequency bins each.
        frequencies : array, double
            Frequencies of the data in Hz. The number of frequencies must match
            the size of the last dimension of data.
        fft_norm : 'none', 'unitary', 'amplitude', 'rms', 'power', 'psd'
            The kind of Discrete Fourier Transform (DFT) normalization. See
            pyfar.fft.normalization and _[#] for more information. The default
            is 'none', which is typically used for energy signals, such as
            impulse responses.
        comment : str
            A comment related to the data. The default is None.
        dtype : string, optional
            Raw data type of the signal. The default is float64

Thanks a lot @mzjn for taking the time and sharing you experience! This would have taken me at least forever to find. I wrongly thought Parameters and Attributes are interchangeable — fabian, Apr 01 '21 at 11:10
In case it helps someone else: I just got the same warning message from Sphinx for a different reason and found the solution. I mixed class attributes and instance attributes under the "Attributes" section of a class docstring. Turns out it must only be instance attributes. — wheelercj, Nov 12 '21 at 03:22

Sphinx: What is the cause for 'WARNING: duplicate object description'?

1 Answers1