Description
The sphinx-reredirects Sphinx extension would be useful for declaring redirected pages directly in our conf.py when pages get renamed or removed, as opposed to having to set up the redirects manually in RTD (in addition to keeping such redirects under VC which is not currently possible with RTD redirects, it would also work for non-RTD builds of the docs).
Additional context
We've had a few cases where moving or renaming docs have broken things like search results, or in some cases other packages' documentation that links to the Astropy docs (see e.g. #11754). Currently, any time we move documentation around we must also take care to set up redirects in RTD, which can only be done by someone with access to the RTD project. It's easy to miss.
By using a Sphinx extension for this, we can include such redirects in any PR that requires documentation moves.
I've seen some other extensions for this, but this one is quite recent, actively maintained, and seems like one of the simplest to use and quite flexible.
@astrofrog asked
Could we actually replace the redirects configured on RTD with this? The redirects on RTD currently are ‘top level’ in the sense we can add urls at the level of latest/stable/etc - this would only be useful within a set of docs right?
It's a good question and I'm not 100% sure it could replace all use cases for RTD's redirects. But it would be useful in many caes--for example, I wanted to use this for #11367 which requires an old doc page that I want to remove to be replaced with a redirect to a different doc page.
It also could have been used for the redirect of all developer doc pages to the "latest" docs (which prompted #11754) like:
redirects = {
'development/*': 'https://docs.astropy.org/en/latest/$source.html'
}The redirect could also be made contingent on whether or not the docs are being built for RTD.
Description
The sphinx-reredirects Sphinx extension would be useful for declaring redirected pages directly in our
conf.pywhen pages get renamed or removed, as opposed to having to set up the redirects manually in RTD (in addition to keeping such redirects under VC which is not currently possible with RTD redirects, it would also work for non-RTD builds of the docs).Additional context
We've had a few cases where moving or renaming docs have broken things like search results, or in some cases other packages' documentation that links to the Astropy docs (see e.g. #11754). Currently, any time we move documentation around we must also take care to set up redirects in RTD, which can only be done by someone with access to the RTD project. It's easy to miss.
By using a Sphinx extension for this, we can include such redirects in any PR that requires documentation moves.
I've seen some other extensions for this, but this one is quite recent, actively maintained, and seems like one of the simplest to use and quite flexible.
@astrofrog asked
It's a good question and I'm not 100% sure it could replace all use cases for RTD's redirects. But it would be useful in many caes--for example, I wanted to use this for #11367 which requires an old doc page that I want to remove to be replaced with a redirect to a different doc page.
It also could have been used for the redirect of all developer doc pages to the "latest" docs (which prompted #11754) like:
The redirect could also be made contingent on whether or not the docs are being built for RTD.