Redirecting Documents
During documentation lifetime, some source files are moved between folders or renamed, and the original links to these files will be broken. Manually fixing these links one by one is time-consuming.
To solve this issue, the html_redirects.py extension is provided to redirect pages that have changed URLs. The extension is integrated in ESP-Docs.
This extension is used together with a redirection list html_redirect_pages, which is generated by conf_common.py from page_redirects.txt .
conf_common.py is a configuration file for your project. To enable the html_redirects.py extension, you need to add html_redirects.py to its extension list to enable this extension.
page_redirects.txt is a file that includes both old URLs and updated URLs. By reading this file, html_redirects.py generates a redirection list html_redirect_pages, thus redirecting old URLs to updated ones.
If you want to rename a document, for example, rename docs/en/introduction to docs/en/get-started, or redirect a document, for example, redirect docs/en/writing-documentation/basic-syntax to a web page, and do not want to update the links manually, you can follow the below steps.
Open your conf_common.py file and append html_redirects.py to the extensions list, thus enabling it in your project:
extensions += [
...
'generic_extensions.html_redirects'
...
]
This step is done only once for a project.
Create the file docs/page_redirects.txt to include the old and new URLs. conf_common.py will build the list html_redirect_pages from docs/page_redirects.txt. You can check page_redirects.txt as an example.
Add content following the below format to the page_redirects.txt file.
old URL new URL
In the above two scenarios, the URLs added in the file should be:
docs/en/introduction docs/en/get-started
docs/en/writing-documentation/basic-syntax "https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html"
The old URL must be relative to the document root only and MUST NOT contain the file extension, which is .rst in this case.
The new URL can either be an absolute URL or a relative URL.
For absolute URLs, the URLs must be wrapped with double quotation marks. Whatever is inside the quotation marks is used verbatim as the URL. Don’t forget to add the “https://” prefix to your absolute URL.
For relative URLs, the URLs must be relative to the document root only and MUST NOT be wrapped with any quotation marks.
In this way, page_redirects.txt is used as a “recipe” to redirect to the new URLs.