readthedocs / readthedocs/sphinx-autoapi
Sphinx AutoAPI >=3.2 generates duplicate definitions of class attributes
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
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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