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
|
Usage
#####
The extension relies on the ``redirects`` configuration option in ``conf.py``. ``redirects`` option maps a *source* to a *target*.
.. highlight:: python3
::
redirects = {
"<source>": "<target>"
}
By default, ``redirects`` is empty (i.e. generates no redirect files).
*Source* (the key in ``redirects`` map) is a *docname*, i.e. document path without a suffix (an extension). Most Sphinx projects use ``.rst`` as extension. For example, a docname for the file ``index.rst`` is ``index``, for ``agents/intro.rst`` is ``agents/intro``, etc.
Source may be non-existing document or existing document. If source does not exist, |project| creates new redirect .html file. For existing document, document's .html file will be overwritten with redirect file. To select multiple existing documents, a `source wildcards <Wildcard syntax_>`_ can be used.
*Target* (the value in ``redirects`` map) is an URL that will be used in the HTML redirecting file. It may be specified using the placeholder to reuse source docname (see `Target placeholders`_).
Target value must correspond to the output file naming of chosen Sphinx builder. For example, html builder creates ``docname.html``, while dirhtml ``docname/index.html``.
.. important:: The extension works only for HTML-based builders like html and dirhtml. When building to other outputs (linkcheck, latex), it does nothing.
The redirect is relative to the current page. So, if you want to redirect ``guides/index.html`` to ``index.html`` use:
.. highlight:: python3
::
redirects = {
"guides/index": "../index.html"
}
Redirect old documents
**********************
The basic usage is to redirect document you delete or rename to a new file within the same project. For example, if you rename ``setup.rst`` to ``install.rst``::
redirects = {
"setup": "install.html",
}
Newly created ``setup.html`` will contain ``<meta http-equiv="refresh" content="0; url=install.html">``.
Or, if you output to dirhtml, target must be a folder::
redirects = {
"setup": "install/",
}
.. rubric:: Absolute URLs
The target maybe any value. For example, if particular page is now on the different website::
redirects = {
"install/requirements": "https://anotherwebsite.com/docs/requirements.html",
}
It will create ``install`` folder (if it does not exist) and ``requirements.html`` containing ``<meta http-equiv="refresh" content="0; url=https://anotherwebsite.com/docs/requirements.html">``.
Redirect existing documents
***************************
Source (the key in the ``redirects`` option) may be specified with wildcards. If wildcard is used, it means that you want to expand it against existing documents. |project| creates redirect .html file that will overwrite original document's html file.
For example, if all FAQ documents in ``faq/`` folder should be redirected to dedicated forum website, but you don't want to delete them in your documentation::
redirects = {
"faq/*": "https://website.com/forum/faq",
}
Now, html files originally produced by documents in ``faq/`` like ``supported-os.html``, ``licencing.html``, etc., are all replaced with body ``<meta http-equiv="refresh" content="0; url=https://website.com/forum/faq">``
Wildcard syntax
===============
Wildcards for selecting existing source documents know only ``*``, ``?``, ``[seq]`` and ``[!seq]`` patterns.
* ``*`` matches everything, while ``?`` any single character.
* ``[seq]`` matches any character in the seq, ``[!seq]`` any character not in seq.
(If you are curious, matching is using Python3 `fnmatch() <https://docs.python.org/3/library/fnmatch.html>`_.)
.. important:: In other words, for example ``**`` used as "recursive" has no meaning here.
Target placeholders
*******************
Matched document in the source, is available in the target as ``$source`` or ``${source}`` placeholder. Because source notation (a docname) is without suffix, you may need to append ``.html`` or ``/`` suffix after the placeholder.
For example, if all FAQ documents in ``faq/`` folder should be redirected to dedicated forum website with the identical filenames in URL, but you don't want to delete them in your documentation::
redirects = {
"faq/*": "https://website.com/forum/faq/$source",
}
Now, html files originally produced by documents in ``faq/`` like ``supported-os.html``, ``licencing.html``, etc., have replaced bodies like ``<meta http-equiv="refresh" content="0; url=https://website.com/forum/faq/supported-os">``, etc.
Redirect everything
*******************
Occasionally, you have to move complete documentation to a new home. It's easy with wildcard and placeholder::
redirects = {
"*": "https://anotherwebsite.com/docs/$source.html"
}
.. tip:: To help search engines to understand the transfer, update (or set) `html_baseurl <https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_baseurl>`_ option to the new website, too.
|
