Skip to content

DOC: Fix invalid Sphinx cross-references in older whatsnew RST files#64459

Open
Copilot wants to merge 3 commits intomainfrom
copilot/fix-sphinx-cross-references
Open

DOC: Fix invalid Sphinx cross-references in older whatsnew RST files#64459
Copilot wants to merge 3 commits intomainfrom
copilot/fix-sphinx-cross-references

Conversation

Copy link

Copilot AI commented Mar 7, 2026

Running sphinx-build with nitpicky = True produces warnings for broken cross-references in whatsnew files for versions 0.13–0.19, where referenced objects have since been renamed, moved, or removed.

Changes

For each broken reference, either correct it to point to the current documented API or replace with double-backtick literals when no valid target exists.

Corrected to valid references

  • ~pandas.io.json.json_normalize:func:pandas.json_normalize`` (v0.13.0)
  • ~pandas.io.parsers.ParserWarning:class:pandas.errors.ParserWarning`` (v0.14.0)
  • boxplot:func:pandas.plotting.boxplot`` (v0.14.0)
  • ~pandas.io.read_sas (meth) → :func:pandas.read_sas`` (v0.17.0)
  • ~Resampler.ffill/backfill/asfreq (wrong module context) → full pandas.api.typing.Resampler.* paths; backfill corrected to bfill (v0.18.0)
  • union_categoricals:func:pandas.api.types.union_categoricals`` (v0.19.0)
  • :func:datetime.datetime → `:class:`python:datetime.datetime (v0.19.0)

Replaced with backtick literals (objects removed/not in any intersphinx target)

  • Panel.apply, Panel.shift, Panel.major_xs, Panel.minor_xs — Panel removed (v0.13.1, v0.14.0)
  • create_engine, parallel_coordinates, andrews_curves, DateRange, HDFStore.select_column, Timestamp.offset, get_data_yahoo, get_data_google, rolling_sum/max/min (v0.14.0)
  • All rolling_*, expanding_*, ewm* top-level function references; describe, set_names, set_labels, set_levels (v0.15.0)
  • io.wb.download (v0.15.1), SparseSeries.to_coo/from_coo (v0.16.0), pandas.io.gbq.to_gbq (v0.17.0, v0.17.1), py._path.local.LocalPath (v0.17.1), Resampler.fillna (v0.18.0), union_categorical, read_gbq, to_gbq, Panel4D.to_xarray (v0.19.0)
Original prompt

This section details on the original issue you should resolve

<issue_title>DOC: Fix incorrect Sphinx cross references in older, whatsnew restructred text files.</issue_title>
<issue_description>The top level doc/ directory contains reStructuredText files who's names will end in .rst and are used to build the pandas documentation using Sphinx. These files can contain Sphinx cross-referencing syntax to create a link to where the reference is documented. Specifically, the Python cross-referencing syntax is used. Cross references should reference currently documented pandas objects or objects in other libaries specified in the intersphinx_mapping variable in doc/source/conf.py

When sphinx-build command is run with nitpicky = True set in the doc/source/conf.py, the logs will specify the file location, line number, and invalid cross references. Below is a subset of invalid cross references from older whatsnew files

doc/source/whatsnew/v0.13.0.rst:749: WARNING: py:meth reference target not found: pandas.io.json.json_normalize [ref.meth]
doc/source/whatsnew/v0.13.1.rst:32: WARNING: py:meth reference target not found: pandas.Panel.apply [ref.meth]
doc/source/whatsnew/v0.13.1.rst:241: WARNING: py:meth reference target not found: pandas.Panel.apply [ref.meth]
doc/source/whatsnew/v0.13.1.rst:339: WARNING: py:meth reference target not found: pandas.Panel.apply [ref.meth]
doc/source/whatsnew/v0.14.0.rst:330: WARNING: py:class reference target not found: pandas.io.parsers.ParserWarning [ref.class]
doc/source/whatsnew/v0.14.0.rst:455: WARNING: py:func reference target not found: create_engine [ref.func]
doc/source/whatsnew/v0.14.0.rst:643: WARNING: py:func reference target not found: parallel_coordinates [ref.func]
doc/source/whatsnew/v0.14.0.rst:647: WARNING: py:func reference target not found: parallel_coordinates [ref.func]
doc/source/whatsnew/v0.14.0.rst:647: WARNING: py:func reference target not found: andrews_curves [ref.func]
doc/source/whatsnew/v0.14.0.rst:664: WARNING: py:class reference target not found: DateRange [ref.class]
doc/source/whatsnew/v0.14.0.rst:672: WARNING: py:meth reference target not found: HDFStore.select_column [ref.meth]
doc/source/whatsnew/v0.14.0.rst:673: WARNING: py:func reference target not found: Timestamp.offset [ref.func]
doc/source/whatsnew/v0.14.0.rst:674: WARNING: py:func reference target not found: get_data_yahoo [ref.func]
doc/source/whatsnew/v0.14.0.rst:674: WARNING: py:func reference target not found: get_data_google [ref.func]
doc/source/whatsnew/v0.14.0.rst:678: WARNING: py:func reference target not found: rolling_sum [ref.func]
doc/source/whatsnew/v0.14.0.rst:732: WARNING: py:meth reference target not found: Panel.shift [ref.meth]
doc/source/whatsnew/v0.14.0.rst:738: WARNING: py:meth reference target not found: Panel.major_xs [ref.meth]
doc/source/whatsnew/v0.14.0.rst:738: WARNING: py:meth reference target not found: Panel.minor_xs [ref.meth]
doc/source/whatsnew/v0.14.0.rst:742: WARNING: py:func reference target not found: parallel_coordinates [ref.func]
doc/source/whatsnew/v0.14.0.rst:746: WARNING: py:func reference target not found: parallel_coordinates [ref.func]
doc/source/whatsnew/v0.14.0.rst:746: WARNING: py:func reference target not found: andrews_curves [ref.func]
doc/source/whatsnew/v0.14.0.rst:759: WARNING: py:func reference target not found: boxplot [ref.func]
doc/source/whatsnew/v0.14.0.rst:848: WARNING: py:func reference target not found: rolling_max [ref.func]
doc/source/whatsnew/v0.14.0.rst:848: WARNING: py:func reference target not found: rolling_min [ref.func]
doc/source/whatsnew/v0.15.0.rst:400: WARNING: py:func reference target not found: rolling_min [ref.func]
doc/source/whatsnew/v0.15.0.rst:400: WARNING: py:func reference target not found: rolling_max [ref.func]
doc/source/whatsnew/v0.15.0.rst:400: WARNING: py:func reference target not found: rolling_cov [ref.func]
doc/source/whatsnew/v0.15.0.rst:400: WARNING: py:func reference target not found: rolling_corr [ref.func]
doc/source/whatsnew/v0.15.0.rst:427: WARNING: py:func reference target not found: rolling_max [ref.func]
doc/source/whatsnew/v0.15.0.rst:427: WARNING: py:func reference target not found: rolling_min [ref.func]
doc/source/whatsnew/v0.15.0.rst:427: WARNING: py:func reference target not found: rolling_sum [ref.func]
doc/source/whatsnew/v0.15.0.rst:427: WARNING: py:func reference target not found: rolling_mean [ref.func]
doc/source/whatsnew/v0.15.0.rst:427: WARNING: py:func reference target not found: rolling_median [ref.func]
doc/source/whatsnew/v0.15.0.rst:427: WARNING: py:func reference target not ...

</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

- Fixes pandas-dev/pandas#64458

<!-- START COPILOT CODING AGENT TIPS -->
---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. [Learn more about Advanced Security.](https://gh.io/cca-advanced-security)

Co-authored-by: mroeschke <10647082+mroeschke@users.noreply.github.com>
Copilot AI changed the title [WIP] Fix incorrect Sphinx cross references in documentation DOC: Fix invalid Sphinx cross-references in older whatsnew RST files Mar 7, 2026
@mroeschke
Copy link
Member

/preview

@github-actions
Copy link
Contributor

github-actions bot commented Mar 7, 2026

Website preview of this PR available at: https://pandas.pydata.org/preview/pandas-dev/pandas/64459/

Comment on lines +821 to +822
performed with the ``Resampler`` objects with :meth:`~pandas.core.resample.Resampler.bfill`,
:meth:`~pandas.core.resample.Resampler.ffill`, ``fillna`` and :meth:`~pandas.core.resample.Resampler.asfreq` methods.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot change the module paths to reference pandas.api.typing instead of pandas.core.resample

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated in 0c5480e — the Resampler method references now use pandas.api.typing.Resampler instead of pandas.core.resample.Resampler.

Co-authored-by: mroeschke <10647082+mroeschke@users.noreply.github.com>
@mroeschke
Copy link
Member

/preview

@github-actions
Copy link
Contributor

github-actions bot commented Mar 8, 2026

Website preview of this PR available at: https://pandas.pydata.org/preview/pandas-dev/pandas/64459/

@mroeschke mroeschke marked this pull request as ready for review March 8, 2026 01:41
@mroeschke mroeschke added this to the 3.1 milestone Mar 8, 2026
@mroeschke mroeschke added the Docs label Mar 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants