From 50fe1eea15f3f37ffcd667de6d97aa6bda8d6d50 Mon Sep 17 00:00:00 2001 From: Darian Leung Date: Tue, 27 Apr 2021 17:01:24 +0800 Subject: [PATCH] doc: Add support for redirects to external URL This commit adds support for redirections to external URLs in the html_redirects.py extension --- docs/extensions/html_redirects.py | 16 +++-- docs/page_redirects.txt | 105 ++++++++++++++++-------------- 2 files changed, 67 insertions(+), 54 deletions(-) diff --git a/docs/extensions/html_redirects.py b/docs/extensions/html_redirects.py index 1614c4372b..52b6a32373 100644 --- a/docs/extensions/html_redirects.py +++ b/docs/extensions/html_redirects.py @@ -19,6 +19,10 @@ # Uses redirect_template.html and the list of pages given in # the file conf.html_redirect_pages # +# Redirections can be internal or absolute (i.e., external). +# - Internal redirects are supplied without quotation marks and must be relative to the document root +# - External redirects are wrapped in doulbe quotation marks and are used verbatim +# # Adapted from ideas in https://tech.signavio.com/2017/managing-sphinx-redirects import os.path @@ -53,15 +57,19 @@ def create_redirect_pages(app): 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)) + if new_url.startswith('\"') and new_url.endswith('\"'): + # This is an absolute redirect. Slice away the surrouding quotation marks and copy the url verbatim + new_url = new_url[1:-1] + else: + # This is an internal redirect. Find the relative url to the target document + new_url = app.builder.get_relative_uri(old_url, new_url) + + print('HTML file %s redirects to URL %s' % (out_file, new_url)) out_dir = os.path.dirname(out_file) if not os.path.exists(out_dir): os.makedirs(out_dir) diff --git a/docs/page_redirects.txt b/docs/page_redirects.txt index ee05a87ab6..920fc41622 100644 --- a/docs/page_redirects.txt +++ b/docs/page_redirects.txt @@ -2,50 +2,55 @@ # # Space delimited # -# New URL should be relative to document root, only) +# The old URL must be relative to the document root only and MUST NOT contain the file extension +# +# The new URL can either be an absolute URL or a relative URL +# - For absolute URLs, the URL must be wrapped in double quotation marks. Whatever is inside the quotation marks is +# used verbatim as the URL. Don't forget to add the "http://" or "https://" prefix to your absolute URL. +# - For relative URLs, must be relative to the document root only and MUST NOT be wrapped with any quotation marks. # # Empty lines and lines starting with # are ignored -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/peripherals/can api-reference/peripherals/twai -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/esp_netif -get-started/idf-monitor api-guides/tools/idf-monitor -get-started-cmake/idf-monitor api-guides/tools/idf-monitor -get-started/get-started-devkitc hw-reference/esp32/get-started-devkitc -get-started/get-started-devkitc-v2 hw-reference/esp32/get-started-devkitc-v2 -get-started/get-started-wrover-kit hw-reference/esp32/get-started-wrover-kit -get-started/get-started-wrover-kit-v2 hw-reference/esp32/get-started-wrover-kit-v2 -get-started/get-started-wrover-kit-v3 hw-reference/esp32/get-started-wrover-kit-v3 -get-started/get-started-pico-kit hw-reference/esp32/get-started-pico-kit -get-started/get-started-pico-kit-v3 hw-reference/esp32/get-started-pico-kit-v3 +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/peripherals/can api-reference/peripherals/twai +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/esp_netif +get-started/idf-monitor api-guides/tools/idf-monitor +get-started-cmake/idf-monitor api-guides/tools/idf-monitor +get-started/get-started-devkitc hw-reference/esp32/get-started-devkitc +get-started/get-started-devkitc-v2 hw-reference/esp32/get-started-devkitc-v2 +get-started/get-started-wrover-kit hw-reference/esp32/get-started-wrover-kit +get-started/get-started-wrover-kit-v2 hw-reference/esp32/get-started-wrover-kit-v2 +get-started/get-started-wrover-kit-v3 hw-reference/esp32/get-started-wrover-kit-v3 +get-started/get-started-pico-kit hw-reference/esp32/get-started-pico-kit +get-started/get-started-pico-kit-v3 hw-reference/esp32/get-started-pico-kit-v3 # The preview 'get-started-cmake' guides are now 'get-started' -get-started-cmake get-started -get-started-cmake/add-idf_path-to-profile get-started/add-idf_path-to-profile -get-started-cmake/eclipse-setup get-started/eclipse-setup -get-started-cmake/establish-serial-connection get-started/establish-serial-connection -get-started-cmake/index get-started/index -get-started-cmake/linux-setup get-started/linux-setup -get-started-cmake/linux-setup-scratch get-started/linux-setup-scratch -get-started-cmake/macos-setup get-started/macos-setup -get-started-cmake/macos-setup-scratch get-started/macos-setup-scratch -get-started-cmake/toolchain-setup-scratch get-started/toolchain-setup-scratch -get-started-cmake/windows-setup get-started/windows-setup -get-started-cmake/windows-setup-scratch get-started/windows-setup-scratch -get-started-cmake/get-started-devkitc hw-reference/esp32/get-started-devkitc -get-started-cmake/get-started-devkitc-v2 hw-reference/esp32/get-started-devkitc-v2 -get-started-cmake/get-started-wrover-kit hw-reference/esp32/get-started-wrover-kit -get-started-cmake/get-started-wrover-kit-v2 hw-reference/esp32/get-started-wrover-kit-v2 -get-started-cmake/get-started-wrover-kit-v3 hw-reference/esp32/get-started-wrover-kit-v3 -get-started-cmake/get-started-pico-kit hw-reference/esp32/get-started-pico-kit -get-started-cmake/get-started-pico-kit-v3 hw-reference/esp32/get-started-pico-kit-v3 +get-started-cmake get-started +get-started-cmake/add-idf_path-to-profile get-started/add-idf_path-to-profile +get-started-cmake/eclipse-setup get-started/eclipse-setup +get-started-cmake/establish-serial-connection get-started/establish-serial-connection +get-started-cmake/index get-started/index +get-started-cmake/linux-setup get-started/linux-setup +get-started-cmake/linux-setup-scratch get-started/linux-setup-scratch +get-started-cmake/macos-setup get-started/macos-setup +get-started-cmake/macos-setup-scratch get-started/macos-setup-scratch +get-started-cmake/toolchain-setup-scratch get-started/toolchain-setup-scratch +get-started-cmake/windows-setup get-started/windows-setup +get-started-cmake/windows-setup-scratch get-started/windows-setup-scratch +get-started-cmake/get-started-devkitc hw-reference/esp32/get-started-devkitc +get-started-cmake/get-started-devkitc-v2 hw-reference/esp32/get-started-devkitc-v2 +get-started-cmake/get-started-wrover-kit hw-reference/esp32/get-started-wrover-kit +get-started-cmake/get-started-wrover-kit-v2 hw-reference/esp32/get-started-wrover-kit-v2 +get-started-cmake/get-started-wrover-kit-v3 hw-reference/esp32/get-started-wrover-kit-v3 +get-started-cmake/get-started-pico-kit hw-reference/esp32/get-started-pico-kit +get-started-cmake/get-started-pico-kit-v3 hw-reference/esp32/get-started-pico-kit-v3 api-guides/build-system-cmake api-guides/build-system api-guides/ulp-cmake api-guides/ulp @@ -57,15 +62,15 @@ api-reference/network/tcpip_adapter api-reference/network/esp_netif security/secure-boot security/secure-boot-v1 # Since ESP32-S2, hw-reference URLs are now namespaced by chip -hw-reference/get-started-devkitc hw-reference/esp32/get-started-devkitc -hw-reference/get-started-devkitc-v2 hw-reference/esp32/get-started-devkitc-v2 -hw-reference/get-started-wrover-kit hw-reference/esp32/get-started-wrover-kit -hw-reference/get-started-wrover-kit-v2 hw-reference/esp32/get-started-wrover-kit-v2 -hw-reference/get-started-wrover-kit-v3 hw-reference/esp32/get-started-wrover-kit-v3 -hw-reference/get-started-pico-kit hw-reference/esp32/get-started-pico-kit -hw-reference/get-started-pico-kit-v3 hw-reference/esp32/get-started-pico-kit-v3 -hw-reference/get-started-ethernet-kit-v1.0 hw-reference/esp32/get-started-ethernet-kit-v1.0 -hw-reference/get-started-ethernet-kit hw-reference/esp32/get-started-ethernet-kit -hw-reference/esp32s2/user-guide-kaluga-1-v1.2 hw-reference/esp32s2/user-guide-esp32-s2-kaluga-1-kit +hw-reference/get-started-devkitc hw-reference/esp32/get-started-devkitc +hw-reference/get-started-devkitc-v2 hw-reference/esp32/get-started-devkitc-v2 +hw-reference/get-started-wrover-kit hw-reference/esp32/get-started-wrover-kit +hw-reference/get-started-wrover-kit-v2 hw-reference/esp32/get-started-wrover-kit-v2 +hw-reference/get-started-wrover-kit-v3 hw-reference/esp32/get-started-wrover-kit-v3 +hw-reference/get-started-pico-kit hw-reference/esp32/get-started-pico-kit +hw-reference/get-started-pico-kit-v3 hw-reference/esp32/get-started-pico-kit-v3 +hw-reference/get-started-ethernet-kit-v1.0 hw-reference/esp32/get-started-ethernet-kit-v1.0 +hw-reference/get-started-ethernet-kit hw-reference/esp32/get-started-ethernet-kit +hw-reference/esp32s2/user-guide-kaluga-1-v1.2 hw-reference/esp32s2/user-guide-esp32-s2-kaluga-1-kit -api-guides/jtag-debugging/configure-wrover api-guides/jtag-debugging/configure-ft2232h-jtag +api-guides/jtag-debugging/configure-wrover api-guides/jtag-debugging/configure-ft2232h-jtag