Sphinx：'WARNING: duplicate object description' 的原因是什么？

Question

我收到多个警告，例如：

警告：pyfar.signal.TimeData.times 的重复对象描述，pyfar.classes_audio 中的其他实例，对其中一个实例使用 :noindex:

但想不通为什么？有人建议我可能在不同的 rst 文件中两次包含相同的对象。但我不认为是这样。

我尝试基于原始包 (https://github.com/pyfar/pyfar/tree/develop/docs) 创建一个最小的工作示例：

获取代码

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

制作虚拟环境

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

构建文档

cd docs
make clean
make html

产量

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.

感谢任何回复，法比安

Answer 1

问题似乎是您在某些 __init__ 方法的文档字符串中使用了 Attributes header。如果将其更改为 Parameters（这是正确的 header），警告就会消失。

示例：

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

Sphinx：'WARNING: duplicate object description' 的原因是什么？

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

python

python-sphinx

autodoc

sphinx-napoleon