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 :confval:`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 :confval:`rediraffe_branch` and :confval:`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 :confval:`rediraffe_branch` and :confval:`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.

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.