readthedocs / readthedocs/sphinx-autoapi

Sphinx AutoAPI >=3.2 generates duplicate definitions of class attributes

Open
#476 9 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
494
Forks
147
Avg merge
9m
Merged PRs (30d)
1

Description

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

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by comparing the RST generated for docs/autoapi/pudl/analysis/timeseries_cleaning/index.rst under sphinx-autoapi 3.2.1 and 3.1.2, then run sphinx-build to reproduce the duplicate warnings. The fix is complete when class attributes are emitted only once while retaining their documentation and type information.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.