Sphinx Extension that redirects non-existent pages to working pages.
Project description
sphinxext-rediraffe
Sphinx Extension to redirect files
This sphinx extension redirects non-existent pages to working pages. Additionally, a builder is provided to check that deleted/renamed files in your git repo are redirected.
Rediraffe supports the html and dirhtml builders.
Note: 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.
Installation
python -m pip install sphinxext-rediraffe
Usage
Add sphinxext.rediraffe to your extensions list in your conf.py
extensions = [
sphinxext.rediraffe,
]
To check that deleted/renamed files in your git repo are in your redirects,
- Make sure
rediraffe_branchandrediraffe_redirectsare set in conf.py. - Run the
rediraffecheckdiffbuilder.
Auto Redirect builder
For convenience, the auto redirect builder can be used to automatically add renamed files to your redirects file. Simply 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- Required for rediraffecheckdiff builder. The branch or commit to diff against.
-
rediraffe_redirects- Required. A filename or dict containing redirects
-
rediraffe_template- Optional. 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; Therefore, 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- Optional. The percentage as an integer representing the accuracy required before auto redirecting with the
rediraffewritediffbuilder. The default is 100.
- Optional. The percentage as an integer representing the accuracy required before auto redirecting with the
Example Config
redirects only (file)
conf.py:
rediraffe_redirects = "redirects.txt"
redirects.txt:
"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 = "master~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 -r test-requirements.txt
- 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.
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file sphinxext-rediraffe-0.2.1.tar.gz.
File metadata
- Download URL: sphinxext-rediraffe-0.2.1.tar.gz
- Upload date:
- Size: 7.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.2.0 pkginfo/1.5.0.1 requests/2.24.0 setuptools/49.3.1 requests-toolbelt/0.9.1 tqdm/4.48.2 CPython/3.8.5
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 80e5176851fa31e8dda17720136a93000e14078c7424ecd243e5c99d4529105c |
|
| MD5 | ec3d535ca9e30f9dedb6c0c3e8bb1d69 |
|
| BLAKE2b-256 | 17f667688791d327a7d1c6fa96f4a4c8df28676c270c20d31c0517055d236799 |
File details
Details for the file sphinxext_rediraffe-0.2.1-py3-none-any.whl.
File metadata
- Download URL: sphinxext_rediraffe-0.2.1-py3-none-any.whl
- Upload date:
- Size: 8.0 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.2.0 pkginfo/1.5.0.1 requests/2.24.0 setuptools/49.3.1 requests-toolbelt/0.9.1 tqdm/4.48.2 CPython/3.8.5
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 8b1307b499b7405d5508d7144bb27d57c93b4ac5ec281ba31954e2328acd601f |
|
| MD5 | e8fca00825ee6521dcd4c61d84672844 |
|
| BLAKE2b-256 | 8276bc4662cc119a01516542ca26ba9066b074bacd050b8ac8e2f38c7c1ac7c2 |
