mirror
/
esp-idf
kopia lustrzana https://github.com/espressif/esp-idf
1
0
Forkuj 0
Kod Zgłoszenia Projekty Wydania Wiki Aktywność

Merge branch 'doc/use_sphinx_reredirect_extension' into 'master' 

Doc: Sphinx uses the sphinx-reredirect extension

See merge request espressif/esp-idf!13293
pull/6974/head
Krzysztof Budzynski 2021-04-23 05:13:37 +00:00
rodzic 64a96ca96d 2be772af1c
commit 3e94dce15e
5 zmienionych plików z 13 dodań i 82 usunięć
Pokaż statystyki Ściągnij plik aktualizacji Ściągnij plik porównania Expand all files Collapse all files

16
docs/conf_common.py
Wyświetl plik

@ -55,8 +55,8 @@ extensions = ['breathe',
'sphinxcontrib.rackdiag', 'sphinxcontrib.rackdiag',
'sphinxcontrib.packetdiag', 'sphinxcontrib.packetdiag',
'sphinxcontrib.cairosvgconverter', 'sphinxcontrib.cairosvgconverter',
'sphinx_reredirects',
'extensions.html_redirects',
'extensions.toctree_filter', 'extensions.toctree_filter',
'extensions.list_filter', 'extensions.list_filter',
'extensions.google_analytics', 'extensions.google_analytics',
@ -260,16 +260,24 @@ project_homepage = 'https://github.com/espressif/esp-idf'
# -- Options for HTML output ---------------------------------------------- # -- 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: with open('../page_redirects.txt') as f:
lines = [re.sub(' +', ' ', line.strip()) for line in f.readlines() if line.strip() != '' and not line.startswith('#')] 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 for line in lines: # check for well-formed entries
if len(line.split(' ')) != 2: if len(line.split(' ')) != 2:
raise RuntimeError('Invalid line in page_redirects.txt: %s' % line) 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 # The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes. # a list of builtin themes.

2
docs/en/contribute/add-ons-reference.rst
Wyświetl plik

@ -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` :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. 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 Third Party Extensions

74
docs/extensions/html_redirects.py
Wyświetl plik

@ -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 = """
<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
Wyświetl plik

@ -9,6 +9,7 @@ sphinx==2.3.1
breathe==4.14.1 breathe==4.14.1
sphinx-copybutton==0.3.0 sphinx-copybutton==0.3.0
sphinx-notfound-page sphinx-notfound-page
sphinx-reredirects==0.0.0
sphinxcontrib-blockdiag==2.0.0 sphinxcontrib-blockdiag==2.0.0
sphinxcontrib-seqdiag==2.0.0 sphinxcontrib-seqdiag==2.0.0
sphinxcontrib-actdiag==2.0.0 sphinxcontrib-actdiag==2.0.0

2
docs/zh_CN/contribute/add-ons-reference.rst
Wyświetl plik

@ -75,8 +75,6 @@ ESP-IDF 中包含多种芯片的双语文档（英文，简体中文）。如运
:idf_file:`docs/extensions/list_filter.py` :idf_file:`docs/extensions/list_filter.py`
Sphinx 扩展功能，提供一个 ``.. list::`` 指令，允许系统根据是否有标签（如 ``:tagname: - list content``）来过滤条目列表。完整描述请参考 Python 文件。 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` 中生成这个重新导向列表。
第三方扩展 第三方扩展