Skip to content

docs: fix broken intersphinx links#442

Open
Ekin-Kahraman wants to merge 2 commits intoscverse:mainfrom
Ekin-Kahraman:fix/intersphinx-links
Open

docs: fix broken intersphinx links#442
Ekin-Kahraman wants to merge 2 commits intoscverse:mainfrom
Ekin-Kahraman:fix/intersphinx-links

Conversation

@Ekin-Kahraman
Copy link
Copy Markdown

@Ekin-Kahraman Ekin-Kahraman commented Apr 8, 2026

Summary

  • Add napoleon_type_aliases for short-form types (ndarray, pd.DataFrame, pd.Series, np.ndarray, pandas.Index) so Napoleon maps them to fully qualified intersphinx targets
  • Remove pd.Series, pd.DataFrame, pandas.core.frame.DataFrame, and ndarray from nitpick_ignore since intersphinx now resolves them correctly
  • Add anndata._core.anndata.AnnData to nitpick_ignore (autodoc resolves the runtime module path for base-class references, which intersphinx cannot remap)

Closes #437

Test plan

  • make html in docs/ builds with zero warnings

Add napoleon_type_aliases to map short-form type names (ndarray,
pd.DataFrame, pd.Series, etc.) used in docstrings to their fully
qualified intersphinx targets. Remove the now-unnecessary pandas/numpy
entries from nitpick_ignore since intersphinx can resolve them properly.

Add anndata._core.anndata.AnnData to nitpick_ignore as autodoc resolves
the runtime module path for base-class references which intersphinx
cannot remap.

Closes scverse#437

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@grst
Copy link
Copy Markdown
Collaborator

grst commented Apr 9, 2026

<unknown>:1: WARNING: py:class reference target not found: pandas.core.frame.DataFrame [ref.class]
<unknown>:1: WARNING: py:class reference target not found: pandas.core.frame.DataFrame [ref.class]
<unknown>:1: WARNING: py:class reference target not found: pandas.core.frame.DataFrame [ref.class]
<unknown>:1: WARNING: py:class reference target not found: pandas.core.frame.DataFrame [ref.class]

autodoc resolves pd.DataFrame type annotations to the internal
module path pandas.core.frame.DataFrame, which is not in the pandas
intersphinx inventory (only pandas.DataFrame is). Add to nitpick_ignore.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@Ekin-Kahraman
Copy link
Copy Markdown
Author

Thanks for the review @grst!

pandas.core.frame.DataFrame warnings -- Fixed in 77987f4. The issue is that autodoc resolves pd.DataFrame type annotations to the runtime internal path pandas.core.frame.DataFrame, but the pandas intersphinx inventory only exposes the public API path pandas.DataFrame. This is the same pattern as the existing anndata._core.anndata.AnnData entry, so I added it to nitpick_ignore with an explanatory comment.

CI failure (Python 3.11) -- The "Compile docs" step is the only thing failing, and it's the same step that's been failing on main too (every scheduled run since at least April 2 has the same failure). On main the warning is the pre-existing anndata._core.anndata.AnnData one that this PR already addresses. With the pandas fix pushed, this PR should now resolve both warnings and get CI green.

Copy link
Copy Markdown
Collaborator

@BorisMuzellec BorisMuzellec left a comment

Choose a reason for hiding this comment

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

LGTM, thanks a lot @Ekin-Kahraman !

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

fix broken intersphinx links

3 participants