1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
|
===================
sphinxext-rediraffe
===================
.. role:: code-py(code)
:language: Python
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
============
.. code-block:: sh
python -m pip install sphinxext-rediraffe
Usage
=====
Just add ``sphinxext.rediraffe`` to the extensions list in :file:`conf.py`,
.. code-block:: python
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:
1. Set :confval:`rediraffe_branch` and :confval:`rediraffe_redirects`
in :file:`conf.py`.
2. 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:
1. Set :confval:`rediraffe_branch` and :confval:`rediraffe_redirects`
in :file:`conf.py`.
2. 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 :file:`conf.py` of your Sphinx project.
.. confval:: rediraffe_branch
:type: :code-py:`str`
:default: :code-py:`''`
**Required** for the ``rediraffecheckdiff`` & ``rediraffewritediff`` builders.
The branch or commit to diff against.
.. confval:: rediraffe_redirects
:type: :code-py:`str | dict[str, str]`
A filename or dict containing redirects.
.. confval:: rediraffe_template
:type: :code-py:`str`
:default: :code-py:`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 :confval:`!rediraffe_template`:
``from_file``
the file being redirected as written in :confval:`rediraffe_redirects`.
``to_file``
the destination file that from_file is redirected to as written in
:confval:`rediraffe_redirects`.
``from_url``
the path to ``from_url``'s html file (built by rediraffe) relative to the
:confval:`!outdir`.
``to_url``
the path to ``to_url``'s built html file relative to the :confval:`!outdir`.
``rel_url``
the relative path from ``from_url`` to ``to_url``.
.. confval:: rediraffe_auto_redirect_perc
:type: :code-py:`int`
:default: :code-py:`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)
---------------------
:file:`conf.py`:
.. code-block:: python
rediraffe_redirects = 'redirects.txt'
:file:`redirects.txt`:
.. code-block:: text
# 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)
---------------------
:file:`conf.py`:
.. code-block:: python
rediraffe_redirects = {
'another.rst': 'index.rst',
'another2.rst': 'another.rst',
}
redirects + diff checker
------------------------
:file:`conf.py`:
.. code-block:: python
rediraffe_redirects = 'redirects.txt'
rediraffe_branch = 'main~1'
redirects with jinja template
-----------------------------
:file:`conf.py`:
.. code-block:: python
rediraffe_redirects = 'redirects.txt'
rediraffe_template = 'template.html'
:file:`template.html`:
.. code-block:: html
<html>
<body>
<p>Your destination is {{to_url}}</p>
</body>
</html>
A complex example can be found at :file:`tests/roots/ext/`.
Testing
=======
Rediraffe uses pytest for testing.
To run tests:
1. Install this package
2. Install test dependencies
.. code-block:: sh
python -m pip install --group test
3. Navigate to the tests directory and run
.. code-block:: sh
python -m pytest --headless
The ``--headless`` flag ensures that a browser window does not open
during browser backed selenium testing.
|
