alex/esp-idf
alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2024-10-05 20:47:46 -04:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Merge branch 'revert-3e94dce1' into 'master'

Browse Source 
Revert "Merge branch 'doc/use_sphinx_reredirect_extension' into 'master'"

See merge request espressif/esp-idf!13311
This commit is contained in:
Krzysztof Budzynski 2021-04-23 07:15:17 +00:00
commit a6a440c238
5 changed files with 82 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
docs/conf_common.py
View File

@ -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.

2
docs/en/contribute/add-ons-reference.rst
View File

@ -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

74
docs/extensions/html_redirects.py Normal file
View File

@ -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 = """
<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')
# 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 []

1
docs/requirements.txt
View File

@ -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

2
docs/zh_CN/contribute/add-ons-reference.rst
View File

@ -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` 中生成这个重新导向列表。
第三方扩展