From b240a181b7215158ef4db22ee7e694f938868502 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Mon, 3 Dec 2018 17:58:08 +1100 Subject: [PATCH] docs: Add option to redirect documentation pages which have moved --- docs/conf_common.py | 17 ++++++++++- docs/html_redirects.py | 68 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 84 insertions(+), 1 deletion(-) create mode 100644 docs/html_redirects.py diff --git a/docs/conf_common.py b/docs/conf_common.py index a2dd2b946..17fcc7f0e 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -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' diff --git a/docs/html_redirects.py b/docs/html_redirects.py new file mode 100644 index 000000000..a4012cd73 --- /dev/null +++ b/docs/html_redirects.py @@ -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 = """ + + + + + + +

Page has moved here.

+ + +""" + + +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)