@pllim. Purely cosmetic, so push to next milestone?

Alternatively, I can definitely do this for Friday.

This looks uncontroversial enough that it might still make it into 4.3. Though, we might want to document that this is how we want the refs to be done in the dev doc for... doc.

I'll add a note to that effect.

Darn. Pytest doc sub is flaky. Will try to fix.

@taldcroft, @adrn - as two "randomly" chosen others to have a look at this: do you agree with the concept of centralizing aliases used in the docs? I've reviewed this and the implementation is all OK with me (modulo a small change easily fixed), so if you agree that the idea is sound, I'll merge.

I agree with the concept! Unfortunately don't have time to review this in detail today, maybe tomorrow...

I agree with the concept.

@adrn, @taldcroft - no need to review, as I think I was thorough enough; the agreement with the concept was what I was looking for!

@nstarman - ping me when you removed the OrderedDict short-cut and we'll get this in! But also do check the readthedocs failure - looks related!

@mhvk. Ok. I finally managed to resolve the RTD issues with pytest. Turns out it was very similar to https://thomas-cokelaer.info/blog/2020/04/sphinx-raise-a-warning-duplicate-explicit-target-name/. I'm going to be pushing my changes a few pieces at a time to make sure I resolved the behavior and didn't break any docs links. I'll ping you when it's all done!

Hunting down that problem was a fair bit of work because adding subs to rst_epilog appends them to every file and tox -e build_docs doesn't show you the specific file that raises the error when rst_epilog has the sub and the file has a non-anonymous link of the same name. I'm trying to find a place in the documentation to add a note about this. @mhvk, any suggestions?

Ok, @mhvk, except for a possible note in the dev docs, this is G2G!

I see a lot of potential for followup:

• More link consolidation. I was pretty conservative: only collapsing ReST substitutions and transcluded files.
• Replacing near-duplicated links with their rst_epilog counterparts.
• using the links in docstrings. Here, I almost successfully avoided touching anything not in the docs.

@nstarman - OK, let's get this in! Probably good to have separate issue(s) for the follow-up. My overall sense is to keep it relatively limited, as you have it here, and otherwise err on the side of having references close to where they are needed.

Thank you for doing this. I wonder if we could move all of these into a separate file from conf.py though? I feel like it's a big chunk of the file now and makes it harder to read. It's also not super clear that it's a place now to put common links to use throughout the docs.

I propose moving it out to something like docs/common_links.txt that can be read in by conf.py.

Separating it out sounds good.

@embray . I like the idea. I had kept the substitutions grouped by subpackages, but still all squashed together. This will allow them to be a little more separate.

@embray @mhvk, I opened #11624