sphinx-autoapi icon indicating copy to clipboard operation
sphinx-autoapi copied to clipboard

Sphinx AutoAPI >=3.2 generates duplicate definitions of class attributes

Open zaneselvans opened this issue 6 months ago • 4 comments

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

zaneselvans avatar Aug 09 '24 23:08 zaneselvans