Crash_Override
/
OVMS3-idf
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

docs: Add option to redirect documentation pages which have moved

This commit is contained in:
Angus Gratton 2018-12-03 17:58:08 +11:00 committed by Angus Gratton
parent 6a4955ef74
commit b240a181b7
2 changed files with 84 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
docs/conf_common.py
View File

@ -140,7 +140,8 @@ extensions = ['breathe',
'sphinxcontrib.actdiag',
'sphinxcontrib.nwdiag',
'sphinxcontrib.rackdiag',
'sphinxcontrib.packetdiag'
'sphinxcontrib.packetdiag',
'html_redirects',
]
# Set up font for blockdiag, nwdiag, rackdiag and packetdiag
@ -232,6 +233,20 @@ pygments_style = 'sphinx'
# -- 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
# a list of builtin themes.
html_theme = 'sphinx_rtd_theme'

68
docs/html_redirects.py Normal file
View 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)