docs: Add option to redirect documentation pages which have moved
This commit is contained in:
parent
6a4955ef74
commit
b240a181b7
|
@ -140,7 +140,8 @@ extensions = ['breathe',
|
||||||
'sphinxcontrib.actdiag',
|
'sphinxcontrib.actdiag',
|
||||||
'sphinxcontrib.nwdiag',
|
'sphinxcontrib.nwdiag',
|
||||||
'sphinxcontrib.rackdiag',
|
'sphinxcontrib.rackdiag',
|
||||||
'sphinxcontrib.packetdiag'
|
'sphinxcontrib.packetdiag',
|
||||||
|
'html_redirects',
|
||||||
]
|
]
|
||||||
|
|
||||||
# Set up font for blockdiag, nwdiag, rackdiag and packetdiag
|
# Set up font for blockdiag, nwdiag, rackdiag and packetdiag
|
||||||
|
@ -232,6 +233,20 @@ pygments_style = 'sphinx'
|
||||||
|
|
||||||
# -- Options for HTML output ----------------------------------------------
|
# -- Options for HTML output ----------------------------------------------
|
||||||
|
|
||||||
|
# Custom added feature to allow redirecting old URLs
|
||||||
|
#
|
||||||
|
# list of tuples (old_url, new_url) for pages to redirect
|
||||||
|
# (URLs should be relative to document root, only)
|
||||||
|
html_redirect_pages = [('api-reference/ethernet/index', 'api-reference/network/index'),
|
||||||
|
('api-reference/ethernet/esp_eth', 'api-reference/network/esp_eth'),
|
||||||
|
('api-reference/mesh/index', 'api-reference/network/index'),
|
||||||
|
('api-reference/mesh/esp_mesh', 'api-reference/network/esp_mesh'),
|
||||||
|
('api-reference/wifi/index', 'api-reference/network/index'),
|
||||||
|
('api-reference/wifi/esp_now', 'api-reference/network/esp_now'),
|
||||||
|
('api-reference/wifi/esp_smartconfig', 'api-reference/network/esp_smartconfig'),
|
||||||
|
('api-reference/wifi/esp_wifi', 'api-reference/network/esp_wifi'),
|
||||||
|
('api-reference/system/tcpip_adapter', 'api-reference/network/tcpip_adapter'),]
|
||||||
|
|
||||||
# The theme to use for HTML and HTML Help pages. See the documentation for
|
# The theme to use for HTML and HTML Help pages. See the documentation for
|
||||||
# a list of builtin themes.
|
# a list of builtin themes.
|
||||||
html_theme = 'sphinx_rtd_theme'
|
html_theme = 'sphinx_rtd_theme'
|
||||||
|
|
68
docs/html_redirects.py
Normal file
68
docs/html_redirects.py
Normal file
|
@ -0,0 +1,68 @@
|
||||||
|
# Copyright 2018-2019 Espressif Systems (Shanghai) PTE LTD
|
||||||
|
#
|
||||||
|
# Licensed under the Apache License, Version 2.0 (the "License");
|
||||||
|
# you may not use this file except in compliance with the License.
|
||||||
|
# You may obtain a copy of the License at
|
||||||
|
#
|
||||||
|
# http://www.apache.org/licenses/LICENSE-2.0
|
||||||
|
#
|
||||||
|
# Unless required by applicable law or agreed to in writing, software
|
||||||
|
# distributed under the License is distributed on an "AS IS" BASIS,
|
||||||
|
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||||
|
# See the License for the specific language governing permissions and
|
||||||
|
# limitations under the License.
|
||||||
|
#
|
||||||
|
|
||||||
|
|
||||||
|
# Mechanism to generate static HTML redirect pages in the output
|
||||||
|
#
|
||||||
|
# Uses redirect_template.html and the list of pages given in
|
||||||
|
# conf.html_redirect_pages
|
||||||
|
#
|
||||||
|
# Adapted from ideas in https://tech.signavio.com/2017/managing-sphinx-redirects
|
||||||
|
import os.path
|
||||||
|
|
||||||
|
from sphinx.builders.html import StandaloneHTMLBuilder
|
||||||
|
|
||||||
|
REDIRECT_TEMPLATE = """
|
||||||
|
<html>
|
||||||
|
<head>
|
||||||
|
<meta http-equiv="refresh" content="0; url=$NEWURL" />
|
||||||
|
<script>
|
||||||
|
window.location.href = "$NEWURL"
|
||||||
|
</script>
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<p>Page has moved <a href="$NEWURL">here</a>.</p>
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
|
"""
|
||||||
|
|
||||||
|
|
||||||
|
def setup(app):
|
||||||
|
app.add_config_value('html_redirect_pages', [], 'html')
|
||||||
|
app.connect('build-finished', create_redirect_pages)
|
||||||
|
|
||||||
|
|
||||||
|
def create_redirect_pages(app, docname):
|
||||||
|
if not isinstance(app.builder, StandaloneHTMLBuilder):
|
||||||
|
return # only relevant for standalone HTML output
|
||||||
|
|
||||||
|
for (old_url, new_url) in app.config.html_redirect_pages:
|
||||||
|
print("Creating redirect %s to %s..." % (old_url, new_url))
|
||||||
|
if old_url.startswith('/'):
|
||||||
|
print("Stripping leading / from URL in config file...")
|
||||||
|
old_url = old_url[1:]
|
||||||
|
|
||||||
|
new_url = app.builder.get_relative_uri(old_url, new_url)
|
||||||
|
out_file = app.builder.get_outfilename(old_url)
|
||||||
|
print("HTML file %s redirects to relative URL %s" % (out_file, new_url))
|
||||||
|
|
||||||
|
out_dir = os.path.dirname(out_file)
|
||||||
|
if not os.path.exists(out_dir):
|
||||||
|
os.makedirs(out_dir)
|
||||||
|
|
||||||
|
content = REDIRECT_TEMPLATE.replace("$NEWURL", new_url)
|
||||||
|
|
||||||
|
with open(out_file, "w") as rp:
|
||||||
|
rp.write(content)
|
Loading…
Reference in a new issue