sphinxext-rediraffe¶

This Sphinx extension redirects non-existent pages to working pages. Rediraffe can also check that deleted or renamed files in your git repo are redirected.

Rediraffe creates a graph of all specified redirects and traverses it to point all internal urls to leaf urls. This means that chained redirects will be resolved. For example, if a config has 6 chained redirects, all 6 links will redirect directly to the final link. The end user will never experience more than 1 redirection.

Note: Rediraffe supports the html and dirhtml builders.

Installation¶

python -m pip install sphinxext-rediraffe

Usage¶

Just add sphinxext.rediraffe to the extensions list in conf.py,

extensions = [
   'sphinxext.rediraffe',
]

and set rediraffe_redirects to a dict or file of redirects.

Diff Checker¶

The diff checker ensures that deleted or renamed files in your git repo are in your redirects.

To run the diff checker:

Set rediraffe_branch and rediraffe_redirects in conf.py.
Run the rediraffecheckdiff builder.

Auto Redirect builder¶

The auto redirect builder can be used to automatically add renamed files to your redirects file. Simply run the rediraffewritediff builder.

To run the auto redirecter:

Set rediraffe_branch and rediraffe_redirects in conf.py.
Run the rediraffewritediff builder.

Note: The auto redirect builder only works with a configuration file.

Note: Deleted files cannot be added to your redirects file automatically.

Options¶

These values are placed in the conf.py of your Sphinx project.

rediraffe_branch¶

Type:: str
Default:: ''

Required for the rediraffecheckdiff & rediraffewritediff builders. The branch or commit to diff against.

rediraffe_redirects¶

Type:: str | dict[str, str]

A filename or dict containing redirects.

rediraffe_template¶

Type:: str
Default:: None

A jinja template to use to render the inserted redirecting files. If not specified, a default template will be used. This template will only be accessed after the html/htmldir builder is finished, meaning that this file may be generated as part of your build.

Variables available to rediraffe_template:

from_file: the file being redirected as written in rediraffe_redirects.
to_file: the destination file that from_file is redirected to as written in rediraffe_redirects.
from_url: the path to from_url’s html file (built by rediraffe) relative to the outdir.
to_url: the path to to_url’s built html file relative to the outdir.
rel_url: the relative path from from_url to to_url.

rediraffe_auto_redirect_perc¶

Type:: int
Default:: 100

Only used by the rediraffewritediff builder. The percentage as an integer representing the accuracy required before auto redirecting with the rediraffewritediff builder.

Example Config¶

redirects only (file)¶

conf.py:

rediraffe_redirects = 'redirects.txt'

redirects.txt:

# comments start with '#'
'another file.rst' index.rst
another2.rst "another file.rst"

Note: Filepaths can be wrapped in quotes (single or double). This is especially useful for filepaths containing spaces.

redirects only (dict)¶

conf.py:

rediraffe_redirects = {
    'another.rst': 'index.rst',
    'another2.rst': 'another.rst',
}

redirects + diff checker¶

conf.py:

rediraffe_redirects = 'redirects.txt'
rediraffe_branch = 'main~1'

redirects with jinja template¶

conf.py:

rediraffe_redirects = 'redirects.txt'
rediraffe_template = 'template.html'

template.html:

<html>
  <body>
    <p>Your destination is {{to_url}}</p>
  </body>
</html>

A complex example can be found at tests/roots/ext/.

Testing¶

Rediraffe uses pytest for testing. To run tests:

Install this package
Install test dependencies
```
python -m pip install --group test
```
Navigate to the tests directory and run
```
python -m pytest --headless
```

The --headless flag ensures that a browser window does not open during browser backed selenium testing.