godot-docs/_tools/redirects/README.md

ReadTheDocs redirect tools

The scripts located in this directory help in creating and maintaining redirects on Read the Docs. Also refer to Read the Docs API documentation.

Note that RTD redirects only apply in case of 404 errors, and to all branches and languages: https://docs.readthedocs.io/en/stable/user-defined-redirects.html. If this ever changes, we need to rework how we manage these (likely adding per-branch logic).

convert_git_renames_to_csv.py creates a list of renamed files in Git to create redirects for. create_redirects.py is used to actually manage redirects on ReadTheDocs.

For more information on the scripts themselves, see their help output.

Setup

To install requirements: pip3 install -r requirements.txt. Git is also required and needs to be available in the PATH. To interact with the Read the Docs API, a valid API key must be set as RTD_AUTH_TOKEN (either as an environment variable or in a .env file).

Usage

Let's say we recently renamed some files in the Git branch 3.4 (compared to the stable branch), and now we want to create redirects for these. For this, we would (after setting up the API token and requirements, see Setup above):

python convert_git_renames_to_csv.py stable 3.4

This should output a list of the redirects to create. Let's append these to the redirects file:

python convert_git_renames_to_csv.py stable 3.4 >> redirects.csv

After this, redirects for renamed files should have been appended to redirects.csv. You may want to double-check that! Now let's submit these to ReadTheDocs and create redirects there:

python create_redirects.py

And that should be it!

The script takes care to not add duplicate redirects if the same ones already exist. The created redirects are also valid for all branches and languages, which works out as they only apply for actually missing files - when a user encounters a 404, that is.

The script also only touches page type redirects, all other types may still be added and managed manually on RTD or via other means. All page redirects need to be managed with these tools however, as they will otherwise just overwrite any changes made elsewhere.