Skip to main content

sphinxext-rediraffe

ci Code style: black

Sphinx Extension to redirect files

Rediraffe

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,

  1. Make sure rediraffe_branch and rediraffe_redirects are set in conf.py.
  2. Run the rediraffecheckdiff builder.

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 rediraffewritediff builder. The default is 100.

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:

  1. Install this package
  2. Install test dependencies
    python -m pip install -r test-requirements.txt
    
  3. 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.

Metadata

Release files for sphinxext-rediraffe 0.2.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sphinxext-rediraffe 0.2.3
File Size Uploaded Provenance Actions
sphinxext-rediraffe-0.2.3.tar.gz 7.2 kB Without provenance Details for sphinxext-rediraffe-0.2.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for sphinxext-rediraffe 0.2.3
File Interpreter ABI Platform Actions
sphinxext_rediraffe-0.2.3-py3-none-any.whl Python 3 none any Details for sphinxext_rediraffe-0.2.3-py3-none-any.whl

Total release size: 15.2 kB

Release files / sphinxext-rediraffe-0.2.3.tar.gz

Download URL sphinxext-rediraffe-0.2.3.tar.gz
Size 7.2 kB
Tags Source
SHA-256 checksum
How to use checksums
38e21589607c3149135fd94b87cdd28924fe3857e2755ff70ded948b4da26711
BLAKE2b-256 checksum
How to use checksums
4426f05e7acaceccd585aa2117cc434e9094f7d1507fa7de58cd17594a2ffeb7
Upload date
Uploaded using Trusted Publishing?
What is 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

Release files / sphinxext_rediraffe-0.2.3-py3-none-any.whl

Download URL sphinxext_rediraffe-0.2.3-py3-none-any.whl
Size 8.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3abc7f8c6c1fecb38e6613ffc1bfb7b0025e9cbb3929ed8aea6b20709571a69d
BLAKE2b-256 checksum
How to use checksums
f060887bff2cffe4e1c67a57bf862ac731cc9d05ff65cd5a222d488f288d02e0
Upload date
Uploaded using Trusted Publishing?
What is 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

Security for sphinxext-rediraffe 0.2.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page