Antoine Vandevenne (anv) 302b5307fa [IMP] redirects: split redirects.txt into multiple, per-version, files

The `redirects.txt` file used to specify redirect rules for renamed or
moved documentation pages is starting to grow too big to be easily
maintainable. The main reason is that the number of redirect rules that
were thought to be required has been largely underestimated when
implementing the 'redirects' extension. At first, we believed that no
guidelines or structure were necessary because only a small amount of
redirect rules would be specified. This proved wrong and the file is now
becoming a mess, making it increasingly difficult to figure out where,
why, when, and if a redirect rule is specified in the file.

As the file is versioned, another issue emerges: conflicts occur every
time a commit is forward-ported to a later version if that commit adds a
redirect rule at the end of the file or at a line that was changed in
the later version. As redirect rules are frequently added, and since
blocks of redirect rules for new versions are added at the end of the
file, this tends to happen a lot.

This commit attempts to hit two birds with one stone by splitting the
`redirects.txt` file into multiple files, one per version. While doing
so, the existing redirect rules are ordered alphabetically and moved
into contextual blocks. Instructions and guidelines on how to create
redirect rules are also listed in the `redirects/MANUAL.md` file. By
sorting the redirect rules and adding them in different files, the
number of conflicts should decrease by a lot.

task-2891912

closes odoo/documentation#2292

X-original-commit: 0417b95514
Signed-off-by: Antoine Vandevenne (anv) <anv@odoo.com>

2022-06-24 10:29:43 +02:00

3.0 KiB

Raw Blame History

Redirect rules manual

What are redirect rules?

Redirect rules allow redirecting users to a new documentation page when they land on an old page that was either renamed or moved elsewhere. They are specified in .txt files located in the redirects/ directory at the root of the documentation. Each line of these files specifies a single rule that applies to a single documentation page.

How do redirect rules work?

For each redirect rule, the redirects Sphinx extension creates a blank HTML file at the location of the specified target with only the meta http-equiv="refresh" tag in the <head/>. When users visit that HTML file, a client-side redirection is triggered and the browser loads the target documentation page.

See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta#attr-http-equiv for more information.

How do I create a redirect rule?

Open the text file inside redirects/ that matches the version you are currently working on. For example, pick redirects/13.0.txt if you are moving/renaming the source file (.rst file) of a documentation page in version 13.0 of the documentation. If the file does not exist yet, create it.
Look for the block of redirect rules related to the one you want to add. For example, search for a block of redirect rules that start with applications/sales/sales if you are adding a redirect rule for a page in the Sales app. If the block does not exist yet, create it. Ideally, there should be one block per app or scope and redirect rules should be sorted alphabetically.
Add a new line for your redirect rule at the end of the block. The line should follow this pattern:

path/to/old/file.rst path/to/new/file.rst # optional comment

When should I create a redirect rule?

If you move or rename a source file, chances are you need to create a redirect rule for that file. A redirect rule must be added in the following cases:

A source file is renamed.

Example: contributing/documentation/guidelines.rst is renamed to contributing/documentation/rst_guidelines.rst because you add a new content_guidelines.rst file. The redirect rule should be:

contributing/documentation/guidelines.rst contributing/documentation/rst_guidelines.rst
A source file is moved from one location to another.

Example: The page for the developer guidelines is moved from developer/misc/guidelines.rst to contributing/develop/guidelines.rst. The redirect rule should be:

developer/misc/guidelines.rst contributing/develop/guidelines.rst # Move all guidelines in contributing/
Multiple source files are merged into one.

Example: The entire content of administation/install/odoo_sh.rst is moved into administration/odoo_sh.rst and the first file is deleted. The redirect rule should be:

administration/install/odoo_sh.rst administration/odoo_sh.rst # Move all information related to Odoo.sh on a single page

No redirect rule should be created when you delete a source file for which there is no alternative.

3.0 KiB Raw Blame History