sphinx-autoapi
sphinx-autoapi copied to clipboard
Sphinx AutoAPI >=3.2 generates duplicate definitions of class attributes
With the update to the conda-forge
feedstock in #465 I've just upgraded from v3.0.0 to v3.2.1 of sphinx-autoapi
, and am now getting errors like these when I run sphinx-build
, which I never got before:
sphinx.errors.SphinxWarning: /Users/zane/code/catalyst/pudl/docs/autoapi/pudl/analysis/record_linkage/link_cross_year/index.rst:96:duplicate object description of pudl.analysis.record_linkage.link_cross_year.DistanceMatrix.distance_matrix, other instance in autoapi/pudl/analysis/record_linkage/link_cross_year/index, use :no-index: for one of them
or
sphinx.errors.SphinxWarning: /Users/zane/code/catalyst/pudl/docs/autoapi/pudl/analysis/timeseries_cleaning/index.rst:297:duplicate object description of pudl.analysis.timeseries_cleaning.Timeseries.xi, other instance in autoapi/pudl/analysis/timeseries_cleaning/index, use :no-index: for one of them
By installing previous versions of sphinx-autoapi
in my environment using pip
I see that the problem first appears in v3.2.0. In v3.1.2 the docs build fine.
This sounds vaguely like the error that was coming up in #452?
The RST generated by v3.2.1, including the class and its attributes:
.. py:class:: Timeseries(x: numpy.ndarray | pandas.DataFrame)
Multivariate timeseries for anomalies detection and imputation.
.. attribute:: xi
Reference to the original values (can be null).
Many methods assume that these represent chronological, regular timeseries.
.. attribute:: x
Copy of :attr:`xi` with any flagged values replaced with null.
.. attribute:: flags
Flag label for each value, or null if not flagged.
.. attribute:: flagged
Running list of flags that have been checked so far.
.. attribute:: index
Row index.
.. attribute:: columns
Column names.
.. py:attribute:: xi
:type: numpy.ndarray
.. py:attribute:: index
:type: pandas.Index
.. py:attribute:: columns
:type: pandas.Index
.. py:attribute:: x
:type: numpy.ndarray
.. py:attribute:: flags
:type: numpy.ndarray
.. py:attribute:: flagged
:type: list[str]
:value: []
vs. by v3.1.2:
.. py:class:: Timeseries(x: numpy.ndarray | pandas.DataFrame)
Multivariate timeseries for anomalies detection and imputation.
.. attribute:: xi
Reference to the original values (can be null).
Many methods assume that these represent chronological, regular timeseries.
.. attribute:: x
Copy of :attr:`xi` with any flagged values replaced with null.
.. attribute:: flags
Flag label for each value, or null if not flagged.
.. attribute:: flagged
Running list of flags that have been checked so far.
.. attribute:: index
Row index.
.. attribute:: columns
Column names.
So it seems like AutoAPI is generating two versions of the attributes -- one with the py:
prefix (which includes type information) and one without (which includes the attribute docstrings).