astropy/astropy#11684 shows that this will not break astropy due to circular imports.
I don't think this will be super testable until astropy 4.3 is the 'stable' version in the intersphinx connection. @adrn and I have a PR in gala to test this when v4.3 happens. astropy/astropy#11684 is likewise set up for testing this PR in astropy itself (with intersphinx fixes in #astropy/astropy#11690).

I'm not convinced about the cross-reference/dependency with astropy, this may cause problems in the future. Could we put a static list instead ? I guess the list doesn't change often so we could avoid the dynamic generation.
Also numpydoc xref should be disabled by default (which is the case here I think), and we could just provide numpydoc_xref_aliases_astropy_glossary and numpydoc_xref_aliases_astropy_physical_type (no matter the astropy version) and tell people to include what they need in numpydoc_xref_aliases.

I'm not convinced about the cross-reference/dependency with astropy, this may cause problems in the future.

Do you mean having astropy be a run-time requirement of this package? I was initially concerned (hence astropy/astropy#11684) as I wasn't sure that the local package (astropy) got installed before the documentation requirements, but since it does, there shouldn't be any issues unless the installation order changes. I think PIP and Conda handle that, or does TOX also have a say? I feel good about PIP and Conda, but am not overly familiar with tox.

Could we put a static list instead ? I guess the list doesn't change often so we could avoid the dynamic generation.

The issue then is that any time astropy wants to update the list, sphinx-astropy needs a new release. Dynamic generation obviates the maintainer burden.

Also numpydoc xref should be disabled by default (which is the case here I think)

Agreed. It is here. I have a comment explaining how to turn it on.

and we could just provide numpydoc_xref_aliases_astropy_glossary and numpydoc_xref_aliases_astropy_physical_type (no matter the astropy version) and tell people to include what they need in numpydoc_xref_aliases.

I don't think I understand what you're suggesting here. Could you please clarify what would go into numpydoc_xref_aliases? Right now I have it aggregate all the astropy additions to numpydoc xref. Thanks!

One large danger with adding sphinx links to the numpydoc xref regardless of astropy version is that they can cause the docs to fail, depending on the astropy version. I don't think NOT including them will fail a numpydoc xref unless the the docs are built with an earlier version of astropy than is supported in the code.

ping @astrofrog @pllim @saimn @bsipocz.
I've cleaned up the dynamic generation and now that astropy/astropy#11690 is in, the intersphinx links in numpydoc_xref_aliases_astropy_glossary, and numpydoc_xref_aliases_astropy_physical_type can programagically work in Astropy! It should be convenient for both Astropy and affiliate packages. The Astropy side will be implemented with astropy/astropy#11684.

@saimn, I've incorporated @astrofrog's suggestion to make Astropy an optional dependency. The xref dictionaries are empty if Astropy is not installed or <v4.3 and full otherwise. Does this address the points you raised about cross-dependencies and working around that by static lists?

Given the approval, I've squashed some unnecessary commits.
Also, I changed the version check from float(astropy.__version__[:3]) >= 4.3 to minversion(astropy, "4.3"). Much cleaner.

GTG.

Thanks @nstarman !

Thanks for the reviews!
Now to get this into Astropy. But I guess that will require a new release of sphinx-astropy? Or is there a nightly release or something?

Re: release -- Probably needs a new release but... @saimn , looks like we never set up a auto publish workflow here. Hmm!

Yep, will try to set it up in the coming days.

@nstarman , this is now in https://pypi.org/project/sphinx-astropy/1.4/

Awesome! Thanks.
Now I can get this in for Astropy main.

Many thanks to @saimn ! 😸