From 632b5c40e67a17485b76df1bf3b9d82b2d79a94d Mon Sep 17 00:00:00 2001 From: Krzysztof Budzynski Date: Fri, 23 Apr 2021 13:44:40 +0800 Subject: [PATCH] Revert "Merge branch 'doc/use_sphinx_reredirect_extension' into 'master'" This reverts merge request !13293 --- docs/conf_common.py | 16 ++--- docs/en/contribute/add-ons-reference.rst | 2 + docs/extensions/html_redirects.py | 74 +++++++++++++++++++++ docs/requirements.txt | 1 - docs/zh_CN/contribute/add-ons-reference.rst | 2 + 5 files changed, 82 insertions(+), 13 deletions(-) create mode 100644 docs/extensions/html_redirects.py diff --git a/docs/conf_common.py b/docs/conf_common.py index 687ff1b7c5..b633a9d118 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,24 +260,16 @@ project_homepage = 'https://github.com/espressif/esp-idf' # -- Options for HTML output ---------------------------------------------- -# Add redirections for sphinx_reredirects extension +# Custom added feature to allow redirecting old URLs # -# sphinx_reredirects requires extensions be specified in a Dictionary called 'redirects' -# See https://pypi.org/project/sphinx-reredirects/ for more details +# Redirects should be listed in page_redirects.xt # -# 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) - else: - old_path = line.split(' ')[0] - new_path = line.split(' ')[1] - redirects[old_path] = new_path +html_redirect_pages = [tuple(line.split(' ')) for line in lines] # 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 0344318974..d0be0269b3 100644 --- a/docs/en/contribute/add-ons-reference.rst +++ b/docs/en/contribute/add-ons-reference.rst @@ -75,6 +75,8 @@ 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 new file mode 100644 index 0000000000..1614c4372b --- /dev/null +++ b/docs/extensions/html_redirects.py @@ -0,0 +1,74 @@ +# 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 7e1fd400f0..7fc0de8102 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -9,7 +9,6 @@ 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 eefd802942..687ca710f4 100644 --- a/docs/zh_CN/contribute/add-ons-reference.rst +++ b/docs/zh_CN/contribute/add-ons-reference.rst @@ -75,6 +75,8 @@ 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` 中生成这个重新导向列表。 第三方扩展