Document order of redirects (recently created are matched first)

[The-Compiler]

Details

• Read the Docs project URL: https://pytest.readthedocs.io/ / https://docs.pytest.org/
• Build URL (if applicable): See below
• Read the Docs username (if applicable): The-Compiler

A long while ago, we had a reorganize-docs branch. Those outdated docs were around for a long time (partially due to us forgetting the branch, partially due to #8264). Thus, it would be great to keep those links working. To do so, I added an exact redirect:

So far, everything works as expected. Going to en/reorganize-docs/index.html will lead to en/6.2.x/index.html.

Now we're trying to restructure our documentation based on the Divio model. In the process, various pages moved, e.g. en/6.2.x/mark.html is now en/latest/how-to/mark.html.

To keep things working even if people link to the old location with /latest, we added page redirects:

This works great: en/6.2.x/mark.html continues to work and doesn't get redirected (probably because RTD is clever enough to know that the page in fact exists there), while en/latest/mark.html is correctly redirected to en/latest/how-to/mark.html.

So far for the prologue, now on to the problem:

Expected Result

With those two redirects in place, en/reorganize-docs/mark.html should redirect to en/6.2.x/mark.html - since that page exists, the page redirect shouldn't take place.

Actual Result

en/reorganize-docs/mark.html redirects to en/6.2.x/how-to/mark.html, which is a 404.

[stsewd]

Hi, this is kind of expected, since page redirects will redirect the same file in all versions (where the page leads to a 404).

So for https://docs.pytest.org/en/reorganize-docs/mark.html it first redirects to https://docs.pytest.org/en/reorganize-docs/how-to/mark.html (page redirect), and then it redirects to https://docs.pytest.org/en/6.2.x/how-to/mark.html (exact redirect).

I think you could solve this by using another exact redirect instead of a page redirect, so only the given version is redirected, not all versions.

en/6.2.x/mark.html continues to work and doesn't get redirected

We only use redirects when the page leads to a 404.

[The-Compiler]

Ah, I see, thanks. I didn't consider that redirects could be applied the other way around, this way it makes total sense.

This won't be a problem anymore as soon as we get out our next major release (soon™), then we can redirect reorganize-docs to 7.0.x instead (rather than 6.2.x), where those pages exist under their new locations. I'd rather not add exact redirects for the pages, as we'd need to add those ~25 redirects for every new version then, if we want to keep the links working in all versions.

I wonder if it'd make sense to do exact redirects before page redirects? Though I'm assuming there's some other use-case I'm not thinking about this would break...

[Daltz333]

You could look into file based redirects like https://github.com/wpilibsuite/sphinxext-rediraffe where it does redirects alongside your git history.

[stsewd]

I wonder if it'd make sense to do exact redirects before page redirects? Though I'm assuming there's some other use-case I'm not thinking about this would break...

Yeah, we may have some users depending on this behavior. But actually looks like the order comes from the creation date of the redirects, we should document that.

A future improvement would be to allow users to change the order like we do with automation rules.

[stsewd]

This will be solved with #10881. Redirects will now have an explicit order that users can change.