1PYTHON(1) Python PYTHON(1)
2
6 python - Python [image]
7 sphinx-reredirects is the extension for Sphinx documentation projects
9 that handles redirects for moved pages. It generates HTML pages with
10 meta refresh redirects to the new page location to prevent 404 errors
11 if you rename or move your documents.
12 • docs: https://documatt.gitlab.io/sphinx-reredirects
14 • code: https://gitlab.com/documatt/sphinx-reredirects where issues and
16 contributions are welcome
17 Good URLs are never changing URLs. But if you must, sphinx-reredirects
19 helps you manage redirects with ease and from the single place in
20 project's conf.py. For example, if you rename document start to intro,
21 and tell it to sphinx-reredirects, it will generate HTML page
22 start.html with <meta http-equiv="refresh" content="0; url=in‐
23 tro.html">. The extension supports wildcards and moving to different
24 domain too.
25
27 sphinx-reredirects started from the urge to manage redirects for all
28 documents during moving our Tech writer at work blog to the new domain
29 https://documatt.com/blog/.
30
32 Forward Arrow icon by Icons8.
33 sphinx-reredirects is licensed under BSD3.
35 Install and setup
37 Perform:
38 pip3 install sphinx-reredirects
40 Then, open your conf.py and append sphinx_reredirects to the extensions
42 list:
43 extensions = [
45 ...
46 'sphinx_reredirects'
47 ]
48 Usage
50 The extension relies on the redirects configuration option in conf.py.
51 redirects option maps a source to a target.
52 redirects = {
54 "<source>": "<target>"
55 }
56 By default, redirects is empty (i.e. generates no redirect files).
58 Source (the key in redirects map) is a docname, i.e. document path
60 without a suffix (an extension). Most Sphinx projects use .rst as ex‐
61 tension. For example, a docname for the file index.rst is index, for
62 agents/intro.rst is agents/intro, etc.
63 Source may be non-existing document or existing document. If source
65 does not exist,
66 |project|
67 creates new redirect .html file. For existing document, document's
68 .html file will be overwritten with redirect file. To select multiple
69 existing documents, a source wildcards can be used.
70 Target (the value in redirects map) is an URL that will be used in the
72 HTML redirecting file. It may be specified using the placeholder to re‐
73 use source docname (see Target placeholders).
74 Target value must correspond to the output file naming of chosen Sphinx
76 builder. For example, html builder creates docname.html, while dirhtml
77 docname/index.html.
78 IMPORTANT:
80 The extension works only for HTML-based builders like html and
81 dirhtml. When building to other outputs (linkcheck, latex), it does
82 nothing.
83 The redirect is relative to the current page. So, if you want to redi‐
85 rect guides/index.html to index.html use:
86 redirects = {
88 "guides/index": "../index.html"
89 }
90 Redirect old documents
92 The basic usage is to redirect document you delete or rename to a new
93 file within the same project. For example, if you rename setup.rst to
94 install.rst:
95 redirects = {
97 "setup": "install.html",
98 }
99 Newly created setup.html will contain <meta http-equiv="refresh" con‐
101 tent="0; url=install.html">.
102 Or, if you output to dirhtml, target must be a folder:
104 redirects = {
106 "setup": "install/",
107 }
108 Absolute URLs
110 The target maybe any value. For example, if particular page is now on
112 the different website:
113 redirects = {
115 "install/requirements": "https://anotherwebsite.com/docs/requirements.html",
116 }
117 It will create install folder (if it does not exist) and require‐
119 ments.html containing <meta http-equiv="refresh" content="0;
120 url=https://anotherwebsite.com/docs/requirements.html">.
121 Redirect existing documents
123 Source (the key in the redirects option) may be specified with wild‐
124 cards. If wildcard is used, it means that you want to expand it against
125 existing documents.
126 |project|
127 creates redirect .html file that will overwrite original document's
128 html file.
129 For example, if all FAQ documents in faq/ folder should be redirected
131 to dedicated forum website, but you don't want to delete them in your
132 documentation:
133 redirects = {
135 "faq/*": "https://website.com/forum/faq",
136 }
137 Now, html files originally produced by documents in faq/ like sup‐
139 ported-os.html, licencing.html, etc., are all replaced with body <meta
140 http-equiv="refresh" content="0; url=https://website.com/forum/faq">
141 Wildcard syntax
143 Wildcards for selecting existing source documents know only *, ?, [seq]
144 and [!seq] patterns.
145 • * matches everything, while ? any single character.
147 • [seq] matches any character in the seq, [!seq] any character not in
149 seq.
150 (If you are curious, matching is using Python3 fnmatch().)
152 IMPORTANT:
154 In other words, for example ** used as "recursive" has no meaning
155 here.
156 Target placeholders
158 Matched document in the source, is available in the target as $source
159 or ${source} placeholder. Because source notation (a docname) is with‐
160 out suffix, you may need to append .html or / suffix after the place‐
161 holder.
162 For example, if all FAQ documents in faq/ folder should be redirected
164 to dedicated forum website with the identical filenames in URL, but you
165 don't want to delete them in your documentation:
166 redirects = {
168 "faq/*": "https://website.com/forum/faq/$source",
169 }
170 Now, html files originally produced by documents in faq/ like sup‐
172 ported-os.html, licencing.html, etc., have replaced bodies like <meta
173 http-equiv="refresh" content="0; url=https://website.com/forum/faq/sup‐
174 ported-os">, etc.
175 Redirect everything
177 Occasionally, you have to move complete documentation to a new home.
178 It's easy with wildcard and placeholder:
179 redirects = {
181 "*": "https://anotherwebsite.com/docs/$source.html"
182 }
183 TIP:
185 To help search engines to understand the transfer, update (or set)
186 html_baseurl option to the new website, too.
187 FAQ
189 Aren't 301 redirects better?
190 Client-side redirects with meta refresh are okay for search engines,
191 even the most ancient browsers, and users too.
192 |project|
195 extension was created for tech writers who don't want or can't manage
196 redirects with server-side 301 redirects. Generally, SEO consultants
197 recommend server-side redirects created with .htaccess and similar
198 files. However, many documentation is hosted as on static website host‐
199 ing which doesn't support server-side redirects.
200 I know better how to write HTML redirect file
202 By default, created HTML redirect files contains <html><head><meta
203 http-equiv="refresh" content="0; url=${to_uri}"></head></html>.
204 If you want JavaScript redirection instead, wait longer, or whatever,
206 set redirect_html_template option. This option should points to file
207 inside source dir (directory containing conf.py). For example:
208 redirect_html_template_file = "redirect.html.template"
210 Actual target URI requested in configuration is available under
212 ${to_uri} placeholder.
213 Why name "reredirects"?
215 Because the name "redirects" is already taken by another extension. Un‐
216 fortunately, it doesn't fulfil our requirements (the most notable it
217 doesn't support wildcards and placeholders). These were reasons why we
218 decided to bring a new extension.
219 Release notes
221 0.1.2 (2023-05-18)
222 • be explicit about parallel reads (by Feanil Patel)
223 • docs: fix URL in README (by Angus Hollands T)
225 • docs: fix name of redirect template option (by Angus Hollands T)
227 0.1.1 (2022-06-04)
229 • add more tests
230 • add tox.ini
232 • bugfix failure for non-HTML-based Sphinx builders (by Lynn Root W T)
234 • use suffix for redirect HTML file from html_file_suffix config param‐
236 eter (by Robbert Schreuder Hes W)
237 • add type hints (by Daniël van Noord W)
239 • improve docs with comment that redirects are relative (by Daniël van
241 Noord W)
242 • include LICENCE in sdist
244 0.0.1 (2021-04-26)
246 (In Git tagged as v0.1.0.)
247 • bugfix wildcard/non-wildcard implementation and code clean-up
249 • migrate README to Sphinx docs
251 • rewrite Usage article in docs
253 0.0.0 (2020-09-09)
255 Initial release.
256
258 unknown
259 Sep 08, 2023 PYTHON(1)