Allow specifying redirects in readthedocs.yml

[theacodes]

It would be excellent if we can declare redirects within a file in the project, preferably in the readthedocs.yml file.

[ncoghlan]

Some additional context here: @jonparrot is looking to refactor some aspects of the Python Packaging User Guide, and having the redirects defined outside the code base makes that difficult, since they can't be reviewed and merged along with the rest of the PR. Instead, the code needs to be merged without the redirects, and then the redirects added separately through the ReadTheDocs admin interface.

I'm guessing this may reflect an architectural difference in where the redirects are defined (web server) vs the docs being rendered (Sphinx build), but it would definitely be helpful to be able to review redirect definitions just like any other docs change.

[lmazuel]

+1
When you have a lot of changes, we would be able to script the YAML RTD file (instead of clicking 500 times on the UI).

[honzajavorek]

If you're tired managing your redirects manually, I wrote this little tool to do it programmatically: https://github.com/honzajavorek/rtd-redirects

[stsewd]

With the current implementation of redirects, we can have something like this in the yaml file

   redirects:
     prefix:
       # List of strings
       - "/dev/"
     page:
       # Key/value = from/to
       "/example.html": "/example/intro.html"
     exact:
       # Key/value = from/to
       "docs.example.com/dev/install.html": "docs.example.com/en/latest/installing-your-site.html"
     # Those can't be true at the same time, right?
     html-to-dir: false
     dir-to-html: false

More information about redirects https://docs.readthedocs.io/en/latest/user-defined-redirects.html

[agjohnson]

I'm going to close this as there are two large reasons why this feature addition is difficult for us:

• Redirects are currently applied at the project level, not at the version level. You can have a different readthedocs.yml on each branch/version. I think per-version redirects make sense, but we'd have to undo a lot.
• We're not going to include features in our YAML file that alter database state. Redirects are all handled at the application level.

I think API interaction is the correct solution to this problem for now.

[SimonBiggs]

I'd like to provide the feedback that the current interface could be significantly improved by allowed for edits. Or, even better, allowing for the redirects to be edited within an online text editor within the web interface allowing for bulk find and replace and other features automatically.

We have a scenario where I have a large number of redirects that are being ignored because of the prefix redirect. I need to prepend the prefix to every redirect. I can't edit these, and can't do them in bulk, so need to individually need to remove and rewrite every single one.

I suspect that refining the redirect experience in the backend could impact documentation websites all over the web, as currently I often hit the "Maze 404" read the docs page within open source projects. Making this process easier to maintain would benefit open source documentation all over.

Another alternative, is that we do have the capacity for the redirects to be defined within the readthedocs.yml, but we make it so that only the readthedocs.yml within the main default branch is utilised for these "project level" configuration items.

---

Redirect that need editing:

[ssbarnea]

I totally support @SimonBiggs claims, the fact that we cannot control the redirects from the code and we need to use the web admin interface is a bummer and totally against the concept of automation pipeline. It is a human process hindering documentation management.

[humitos]

@ssbarnea you may be interested on the Redirects endpoint from the API: https://docs.readthedocs.io/en/stable/api/v3.html#redirects . You can use to automate your redirects or in-bulk work. It's not "redirects in YAML" but it's better for some use cases than using the Web UI.

[humitos]

@ssbarnea

other automation systems that had the same dilemma, examples github actions and zuul ci, on both the main branch has more authority than others and there are specific configuration options that must happen first on default branch before the build system would use them.

(from #9418 (comment))

Can you provide more details about how it works? Is there some GitHub and Zuul CI documentation that we can read to understand how is the user experience for this?

[ssbarnea]

Now that I seen the readthedoc-cli implementation, I think it would be very easy to include it inside readthedocs publishing process. If the redirects.yml file is found during build, just run the tool on it (on publish) in order to update the redirects on the admin site.

I am going to implement this manually with GHA for now following the example from https://github.com/nextstrain/docs.nextstrain.org -- at least from the command line it worked very well. Ideally you should make the use of cli and additional redirects.yml obsolete once you integrate it inside readthedocs.yml.

PS. Regarding zuul or gihubactions, basically pipelines must be defined in main branch or they will not work, that is in order to prevent abuse from people from outside which could try to modify a pipeline in order to get access to secrets. That is why those CI/CD system trust only config from main repository, even if the jobs themselves may run against a specific branch, pull request. It can get bit more complicated but better not to go into details as these would likely not apply to what RDT does. Because redirects are per-repository, it totally makes sense to only bother about default branch (main or master).

[margamanterola]

I'm rather surprised to see that ReadTheDocs doesn't support redirects through a config file. It seems like such an obvious use case for documentation that is tracked through VCS. Having to go to the admin console means that only whoever has access to that can do the redirection, instead of it being the responsibility of the PR author.

I guess we can try with the GHA workflow, seems like it could work.

As a data point, the project I was working on before, used Hugo for hosting the website + the documentation, and in that case it was super easy to include the redirects directly as part of the PR changes (as described in the first message here). Each file has an "aliases" field in the metadata that handles that (for example this one: https://raw.githubusercontent.com/flatcar/flatcar-docs/main/docs/provisioning/ignition/boot-process.md).