首頁 探索 說明
登入
RT-Thread-packages
/
esp-idf
镜像来自 https://github-proxy.rt-thread.io/RT-Thread-packages/esp-idf.git
2
0
複刻 0
Files 問題管理 0 Wiki
瀏覽代碼

Sphinx uses reredirect extension

This commit removes the custom HTML rediiect extension and uses
the sphinx-reredirect extension instead. The sphinx-reredirect
extension allows for redirection to external links as well as
support for wildcards.
Darian Leung 4 年之前
父節點
bcc7549802
當前提交
2be772af1c
共有 5 個文件被更改，包括 13 次插入 和 82 次删除
統一視圖 顯示文件統計
  1. 12 4
      docs/conf_common.py
  2. 0 2
      docs/en/contribute/add-ons-reference.rst
  3. 0 74
      docs/extensions/html_redirects.py
  4. 1 0
      docs/requirements.txt
  5. 0 2
      docs/zh_CN/contribute/add-ons-reference.rst

+ 12 - 4
docs/conf_common.py
查看文件 

@@ -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',
 
@@ -256,16 +256,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.

+ 0 - 2
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`
 
 :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

+ 0 - 74
docs/extensions/html_redirects.py
查看文件 

@@ -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 - 0
docs/requirements.txt
查看文件 

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

+ 0 - 2
docs/zh_CN/contribute/add-ons-reference.rst
查看文件 

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