diff --git a/docs/conf_common.py b/docs/conf_common.py
index b633a9d118..687ff1b7c5 100644
--- a/docs/conf_common.py
+++ b/docs/conf_common.py
@@ -55,8 +55,8 @@ extensions = ['breathe',
'sphinxcontrib.rackdiag',
'sphinxcontrib.packetdiag',
'sphinxcontrib.cairosvgconverter',
+ 'sphinx_reredirects',
- 'extensions.html_redirects',
'extensions.toctree_filter',
'extensions.list_filter',
'extensions.google_analytics',
@@ -260,16 +260,24 @@ project_homepage = 'https://github.com/espressif/esp-idf'
# -- Options for HTML output ----------------------------------------------
-# Custom added feature to allow redirecting old URLs
+# Add redirections for sphinx_reredirects extension
#
-# Redirects should be listed in page_redirects.xt
+# sphinx_reredirects requires extensions be specified in a Dictionary called 'redirects'
+# See https://pypi.org/project/sphinx-reredirects/ for more details
#
+# We need to read the redirections from page_redirects.txt that are spaced separated
+# and convert them into a Dict
+
+redirects = {}
with open('../page_redirects.txt') as f:
lines = [re.sub(' +', ' ', line.strip()) for line in f.readlines() if line.strip() != '' and not line.startswith('#')]
for line in lines: # check for well-formed entries
if len(line.split(' ')) != 2:
raise RuntimeError('Invalid line in page_redirects.txt: %s' % line)
-html_redirect_pages = [tuple(line.split(' ')) for line in lines]
+ else:
+ old_path = line.split(' ')[0]
+ new_path = line.split(' ')[1]
+ redirects[old_path] = new_path
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
diff --git a/docs/en/contribute/add-ons-reference.rst b/docs/en/contribute/add-ons-reference.rst
index d0be0269b3..0344318974 100644
--- a/docs/en/contribute/add-ons-reference.rst
+++ b/docs/en/contribute/add-ons-reference.rst
@@ -75,8 +75,6 @@ These are Sphinx extensions developed for IDF that don't rely on any IDF-docs-sp
:idf_file:`docs/extensions/list_filter.py`
Sphinx extensions that provides a ``.. list::`` directive that allows filtering of entries in lists based on whether a tag is set, as ``:tagname: - list content``. See the Python file for a more complete description.
-:idf_file:`docs/extensions/html_redirects.py`
- During documentation lifetime, some source files are moved between folders or renamed. This Sphinx extension adds a mechanism to redirect documentation pages that have changed URL by generating in the Sphinx output static HTML redirect pages. The script is used together with a redirection list ``html_redirect_pages``. ``conf_common.py`` builds this list from :idf_file:`docs/page_redirects.txt`.
Third Party Extensions
diff --git a/docs/extensions/html_redirects.py b/docs/extensions/html_redirects.py
deleted file mode 100644
index 1614c4372b..0000000000
--- a/docs/extensions/html_redirects.py
+++ /dev/null
@@ -1,74 +0,0 @@
-# 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
-# the file 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')
- # attaching to this event is a hack, but it's a convenient stage in the build
- # to create HTML redirects
- app.connect('html-collect-pages', create_redirect_pages)
-
- return {'parallel_read_safe': True, 'parallel_write_safe': True, 'version': '0.1'}
-
-
-def create_redirect_pages(app):
- 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)
-
- return []
diff --git a/docs/requirements.txt b/docs/requirements.txt
index 7fc0de8102..7e1fd400f0 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -9,6 +9,7 @@ sphinx==2.3.1
breathe==4.14.1
sphinx-copybutton==0.3.0
sphinx-notfound-page
+sphinx-reredirects==0.0.0
sphinxcontrib-blockdiag==2.0.0
sphinxcontrib-seqdiag==2.0.0
sphinxcontrib-actdiag==2.0.0
diff --git a/docs/zh_CN/contribute/add-ons-reference.rst b/docs/zh_CN/contribute/add-ons-reference.rst
index 687ca710f4..eefd802942 100644
--- a/docs/zh_CN/contribute/add-ons-reference.rst
+++ b/docs/zh_CN/contribute/add-ons-reference.rst
@@ -75,8 +75,6 @@ ESP-IDF 中包含多种芯片的双语文档（英文，简体中文）。如运
:idf_file:`docs/extensions/list_filter.py`
Sphinx 扩展功能，提供一个 ``.. list::`` 指令，允许系统根据是否有标签（如 ``:tagname: - list content``）来过滤条目列表。完整描述请参考 Python 文件。
-:idf_file:`docs/extensions/html_redirects.py`
- 在文档的维护过程中，一些源文件可能会转移位置或被重命名。这个 Sphinx 扩展功能便添加了一个重新导向机制，通过在 Sphinx 输出中生成静态 HTML 重新导向页面来为 URL 地址已改变的文档重新导向。该脚本与重新导向列表 ``html_redirect_pages`` 一起使用。``conf_common.py`` 将负责从 :idf_file:`docs/page_redirects.txt` 中生成这个重新导向列表。
第三方扩展