Readthedocs.org: 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.