Skip to content

feat: add awkward.* aliases to objects.inv for intersphinx - #3958

Merged
TaiSakuma merged 2 commits into
scikit-hep:mainfrom
TaiSakuma:fix-objects-inv-aliases
Apr 15, 2026
Merged

TaiSakuma merged 2 commits into
scikit-hep:mainfrom
TaiSakuma:fix-objects-inv-aliases

Conversation

@TaiSakuma

Copy link
Copy Markdown
Member

Summary

Motivation

Downstream projects that use type annotations like ak.Array or ak.contents.RegularArray have their documentation tools (mkdocstrings, sphinx-autodoc, etc.) resolve these to the fully qualified awkward.* names. Since the inventory only contained ak.* entries, cross-reference lookups failed silently — no links were generated.

With this change, a downstream project like hypothesis-awkward can write:

def arrays(draw, *, regulararray: bool) -> ak.Array:

and its API reference will automatically link ak.Array to the Awkward Array documentation. Similarly, references like [RegularArray][ak.contents.RegularArray] will resolve correctly.

Details

A build-finished Sphinx event handler reads the generated objects.inv, duplicates each ak.* entry with an awkward.* prefix pointing to the same URL, and writes it back.

Test plan

  • Built docs locally with sphinx-build -M html . _build -D nb_execution_mode=off
  • Verified objects.inv contains awkward.Array, awkward.Record, awkward.flatten entries
  • Confirmed a downstream project's intersphinx resolves awkward.Array against the local inventory

Co-Authored-By: Claude Opus 4.6 (1M context) noreply@anthropic.com

Post-process the Sphinx inventory after build to duplicate ak.* entries
as awkward.* so downstream projects can resolve cross-references like
awkward.Array. Closes scikit-hep#3950.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@TaiSakuma

Copy link
Copy Markdown
Member Author

This PR is doc only. It will get stuck again for the same reason as described in #3948 (comment).

I'll touch some code.

@github-actions

github-actions Bot commented Apr 7, 2026

Copy link
Copy Markdown
Contributor

The documentation preview is ready to be viewed at http://preview.awkward-array.org.s3-website.us-east-1.amazonaws.com/PR3958

Docs-only PRs from forks don't trigger the required Tests workflow
(paths-ignore: docs/**). This trivial src/ change forces CI to run.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@TaiSakuma

Copy link
Copy Markdown
Member Author

I pushed 27e637a to trigger the workflows.

@TaiSakuma

TaiSakuma commented Apr 7, 2026 •

Copy link
Copy Markdown
Member Author

The object.inv file in the preview is at http://preview.awkward-array.org.s3-website.us-east-1.amazonaws.com/PR3958/objects.inv.

@TaiSakuma
TaiSakuma requested review from ariostas and ianna April 7, 2026 19:09
@codecov

codecov Bot commented Apr 7, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 85.25%. Comparing base (42b3b92) to head (27e637a).
⚠️ Report is 15 commits behind head on main.

Additional details and impacted files
Files with missing lines Coverage Δ
src/awkward/operations/ak_flatten.py 94.64% <ø> (ø)

... and 9 files with indirect coverage changes

@TaiSakuma
TaiSakuma marked this pull request as ready for review April 9, 2026 16:06

@ianna ianna left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

@TaiSakuma - Thanks! I wonder if this is an old PR and needs an update-- the docs do not expose private members nor the cross links are consistently present:

Image

@TaiSakuma

Copy link
Copy Markdown
Member Author

@ianna This PR fixes a different issue.
#3966 fixed the private members.
#3972 fixes the cross-reference within the same page.

This PR fixes the inventory, which fixes the cross-reference from other docs.

@ianna ianna left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

@TaiSakuma - Fantastic! Thanks for clarification. This PR is ready to merged. Thanks!

@TaiSakuma

Copy link
Copy Markdown
Member Author

For example, in the hypothesis-awkward doc, the Python builtins (e.g., int, bool), NumPy objects (e.g., dtype, ndarray, and Hypothesis objects (e.g., SearchStrategy) are hyper-linked to their API references.

This PR fixes similar links to Awkward objects.

@TaiSakuma
TaiSakuma merged commit b8573aa into scikit-hep:main Apr 15, 2026
41 checks passed
@TaiSakuma
TaiSakuma deleted the fix-objects-inv-aliases branch April 22, 2026 20:45
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.

objects.inv entries use ak.* prefix — breaks intersphinx/mkdocstrings cross-references from downstream projects

2 participants