Use sphinx-astropy xref aliases

[nstarman]

"Upstream" much of the numpydoc xref to sphinx-astropy for use by affiliate packages.

Blocked by: astropy/sphinx-astropy#40

@adrn @mhvk

Tests:

• Open this PR and have a circular / not-circular dependency. Does it error? NOPE 🥳
• If ↑ works, then try allowing astropy's conf.py to use the sphinx_astropy v1 duplicate definitions. Does this use the tested astropy version ?
• If ↑ works, make this a real PR. 🚀

[github-actions]

👋 Thank you for your draft pull request! Do you know that you can use [ci skip] or [skip ci] in your commit messages to skip running continuous integration tests until you are ready?

[adrn]

My instigation, because I asked about https://github.com/astropy/sphinx-astropy/pull/40/files#r624715168

Does this lead to any weird circular dependency issues?

😄

[nstarman]

Hmm. This step appears to be a bit trickier. There's some intersphinx subtleties since the intersphinx_mapping in sphinx_astropy.sphinx refers to astropy, but this is astropy stable, and we want the intersphinx to refer to the version being built.

@pllim @embray , git blame says y'all last modified the line

del intersphinx_mapping['astropy']  # noqa: F405

Any suggestions how to intersphinx to the version being built? Is that even possible? Larger question, is this even a good idea, or should we just keep the physical type xref explicitly in Astropy/docs/conf.py (in addition to in sphinx_astropy v1 for affiliate packages)?

Edit : astropy/sphinx-astropy#15 is relevant.

[pllim]

Any suggestions how to intersphinx to the version being built?

Maybe #11622 is what you need?

p.s. We don't really have enough resources for big changes to sphinx-astropy.

[nstarman]

Maybe #11622 is what you need?

Looks like it. It helped me figure out the solution. Thanks!

p.s. We don't really have enough resources for big changes to sphinx-astropy.

Understood. I'm working with @adrn to enable some of the numpydoc xref to be easily used by affiliate packages. I'm trying to avoid messing with any intersphinx magic, just moving some dictionaries around. Probably nothing big.

[nstarman]

@adrn @mhvk. This works! We can move much of the numpydoc xref stuff from Astropy to sphinx-astropy, thereby allowing affiliate packages to use the xref. I've set it up so that sphinx-astropy creates affiliate links, so here in astropy we just strip the intersphinx parts from the links with two quick .replace() string operations.

There are two things before I undraft:

1. How much should be moved to sphinx-astropy?
2. The sphinx-astropy PR needs to be merged first (intersphinx xref sphinx-astropy#40)

[nstarman]

I think #11690 can be lightly modified (once merged) to skip the need for the intersphinx stripping happening in this PR. That would make astropy_sphinx "just" work for both affiliate and astropy.

[mhvk]

@nstarman - this looks nice, but obviously still needs the astropy-sphinx PR to be merged first...

[nstarman]

astropy-sphinx PR to be merged first

Unfortunately, a new release... No chance that sphinx-astropy could release in lock-step with Astropy (if there's a change in sphinx-astropy) ?

[pllim]

chance that sphinx-astropy could release in lock-step with Astropy

Right now, release is done as needed and when people have time. I won't have time this week.

[nstarman]

Request review: @pllim @saimn @astrofrog @adrn @mhvk

@mhvk @adrn. Failures unrelated?

[pllim]

32-bit/parallel failure is due to #11878 .

I am not sure if I can review this PR. I have not been following the doc stuff closely.

[nstarman]

32-bit/parallel failure is due to #11878 .

Thanks! I was worried there.

I am not sure if I can review this PR.

NP. I tagged because of astropy/sphinx-astropy#40.

[mhvk]

Nice!

[mhvk]

I think this is just ready to go in, as it was a logical follow-up of the sphinx astropy update. But maybe leave open for a day in case others want to have a look.

[nstarman]

reminder to self: really need to do #11584 to also document which x-refs are in sphinx-astropy, how an affiliate package should use all this (also add documentation in sphinx-astropy), and how to add a term to sphinx-astropy and remove in astropy (if present).

[saimn]

Sounds good. I put the milestone to 5.0 but maybe we could backport to avoid conflicts in case we need to update the conf.py file in the future.

[saimn]

I don't think this deserves a changelog entry, it's an internal change not visible by users.

[nstarman]

Done!

[pllim]

As @saimn said, please remove change log.

p.s. @Cadair , does your towncrier check logic not set failure if "no changelog entry needed" label is there but there is a changelog entry?

Addressed

[saimn]

Thanks @nstarman !