This is an automated email from the ASF dual-hosted git repository.
spacewander pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new 6ac80b9 docs: avoid newline in the middle of Chinese sentences (#5948)
6ac80b9 is described below
commit 6ac80b9fb224c150975786a77c0667974d3349e6
Author: 罗泽轩 <[email protected]>
AuthorDate: Thu Dec 30 18:04:09 2021 +0800
docs: avoid newline in the middle of Chinese sentences (#5948)
---
.github/workflows/doc-lint.yml | 11 +++++
docs/zh/latest/admin-api.md | 3 +-
docs/zh/latest/architecture-design/plugin.md | 18 +++-----
docs/zh/latest/architecture-design/route.md | 3 +-
docs/zh/latest/architecture-design/upstream.md | 3 +-
docs/zh/latest/plugin-develop.md | 7 +--
docs/zh/latest/router-radixtree.md | 3 +-
docs/zh/latest/stand-alone.md | 6 +--
utils/fix-zh-doc-segment.py | 59 ++++++++++++++++++++++++++
9 files changed, 84 insertions(+), 29 deletions(-)
diff --git a/.github/workflows/doc-lint.yml b/.github/workflows/doc-lint.yml
index 6f97fb2..2244e37 100644
--- a/.github/workflows/doc-lint.yml
+++ b/.github/workflows/doc-lint.yml
@@ -22,3 +22,14 @@ jobs:
- name: check category
run: |
./utils/check-category.py
+ - name: check Chinese doc
+ run: |
+ sudo pip3 install zhon
+ ./utils/fix-zh-doc-segment.py > \
+ /tmp/check.log 2>&1 || (cat /tmp/check.log && exit 1)
+ if grep "find broken newline in file: " /tmp/check.log; then
+ cat /tmp/error.log
+ echo "Newline can't appear in the middle of Chinese sentences."
+ echo "You need to run ./utils/fix-zh-doc-segment.py to fix them."
+ exit 1
+ fi
diff --git a/docs/zh/latest/admin-api.md b/docs/zh/latest/admin-api.md
index 826a908..404604e 100644
--- a/docs/zh/latest/admin-api.md
+++ b/docs/zh/latest/admin-api.md
@@ -47,8 +47,7 @@ Admin API 是为 Apache APISIX 服务的一组 API，我们可以将参数传递
*地址*：/apisix/admin/routes/{id}?ttl=0
-*说明*：Route 字面意思就是路由，通过定义一些规则来匹配客户端的请求，然后根据匹配结果加载并执行相应的
-插件，并把请求转发给到指定 Upstream。
+*说明*：Route 字面意思就是路由，通过定义一些规则来匹配客户端的请求，然后根据匹配结果加载并执行相应的插件，并把请求转发给到指定 Upstream。
注意：在启用 `Admin API` 时，它会占用前缀为 `/apisix/admin` 的 API。因此，为了避免您设计 API 与
`/apisix/admin` 冲突，建议为 Admin API 使用其他端口，您可以在 `conf/config.yaml` 中通过
`port_admin` 进行自定义 Admin API 端口。
diff --git a/docs/zh/latest/architecture-design/plugin.md
b/docs/zh/latest/architecture-design/plugin.md
index 24f5885..433e7bd 100644
--- a/docs/zh/latest/architecture-design/plugin.md
+++ b/docs/zh/latest/architecture-design/plugin.md
@@ -23,15 +23,12 @@ title: Plugin
`Plugin` 表示将在 `HTTP` 请求/响应生命周期期间执行的插件配置。
-`Plugin` 配置可直接绑定在 `Route` 上，也可以被绑定在 `Service` 或 `Consumer`上。而对于同一
-个插件的配置，只能有一份是有效的，配置选择优先级总是 `Consumer` > `Route` > `Service`。
+`Plugin` 配置可直接绑定在 `Route` 上，也可以被绑定在 `Service` 或
`Consumer`上。而对于同一个插件的配置，只能有一份是有效的，配置选择优先级总是 `Consumer` > `Route` > `Service`。
-在 `conf/config.yaml` 中，可以声明本地 APISIX 节点都支持哪些插件。这是个白名单机制，不在该
-白名单的插件配置，都将会被自动忽略。这个特性可用于临时关闭或打开特定插件，应对突发情况非常有效。
+在 `conf/config.yaml` 中，可以声明本地 APISIX
节点都支持哪些插件。这是个白名单机制，不在该白名单的插件配置，都将会被自动忽略。这个特性可用于临时关闭或打开特定插件，应对突发情况非常有效。
如果你想在现有插件的基础上新增插件，注意需要拷贝 `conf/config-default.yaml` 的插件节点内容到
`conf/config.yaml` 的插件节点中。
-插件的配置可以被直接绑定在指定 Route 中，也可以被绑定在 Service 中，不过 Route 中的插件配置
-优先级更高。
+插件的配置可以被直接绑定在指定 Route 中，也可以被绑定在 Service 中，不过 Route 中的插件配置优先级更高。
一个插件在一次请求中只会执行一次，即使被同时绑定到多个不同对象中（比如 Route 或 Service）。
插件运行先后顺序是根据插件自身的优先级来决定的，例如：
@@ -46,8 +43,7 @@ local _M = {
}
```
-插件配置作为 Route 或 Service 的一部分提交的，放到 `plugins` 下。它内部是使用插件
-名字作为哈希的 key 来保存不同插件的配置项。
+插件配置作为 Route 或 Service 的一部分提交的，放到 `plugins` 下。它内部是使用插件名字作为哈希的 key 来保存不同插件的配置项。
```json
{
@@ -64,8 +60,7 @@ local _M = {
}
```
-并不是所有插件都有具体配置项，比如 `prometheus` 下是没有任何具体配置项，这时候用一个空的对象
-标识即可。
+并不是所有插件都有具体配置项，比如 `prometheus` 下是没有任何具体配置项，这时候用一个空的对象标识即可。
如果一个请求因为某个插件而被拒绝，会有类似这样的 warn 日志：`ip-restriction exits with http status code
403`。
@@ -79,8 +74,7 @@ APISIX 的插件是热加载的，不管你是新增、删除还是修改插件
curl http://127.0.0.1:9080/apisix/admin/plugins/reload -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT
```
-注意：如果你已经在路由规则里配置了某个插件（比如在 `route` 的 `plugins` 字段里面添加了它），然后
-禁用了该插件，在执行路由规则的时候会跳过这个插件。
+注意：如果你已经在路由规则里配置了某个插件（比如在 `route` 的 `plugins`
字段里面添加了它），然后禁用了该插件，在执行路由规则的时候会跳过这个插件。
## stand-alone 模式下的热加载
diff --git a/docs/zh/latest/architecture-design/route.md
b/docs/zh/latest/architecture-design/route.md
index 2fb3a88..86264f8 100644
--- a/docs/zh/latest/architecture-design/route.md
+++ b/docs/zh/latest/architecture-design/route.md
@@ -21,8 +21,7 @@ title: Route
#
-->
-Route 字面意思就是路由，通过定义一些规则来匹配客户端的请求，然后根据匹配结果加载并执行相应的
-插件，并把请求转发给到指定 Upstream。
+Route 字面意思就是路由，通过定义一些规则来匹配客户端的请求，然后根据匹配结果加载并执行相应的插件，并把请求转发给到指定 Upstream。
Route 中主要包含三部分内容：匹配规则（比如 uri、host、remote_addr 等），插件配（限流限速等）和上游信息。
请看下图示例，是一些 Route 规则的实例，当某些属性值相同时，图中用相同颜色标识。
diff --git a/docs/zh/latest/architecture-design/upstream.md
b/docs/zh/latest/architecture-design/upstream.md
index ca1733e..f8561ce 100644
--- a/docs/zh/latest/architecture-design/upstream.md
+++ b/docs/zh/latest/architecture-design/upstream.md
@@ -27,8 +27,7 @@ Upstream 是虚拟主机抽象，对给定的多个服务节点按照配置规
如上图所示，通过创建 Upstream 对象，在 `Route` 用 ID 方式引用，就可以确保只维护一个对象的值了。
-Upstream 的配置可以被直接绑定在指定 `Route` 中，也可以被绑定在 `Service` 中，不过 `Route` 中的配置
-优先级更高。这里的优先级行为与 `Plugin` 非常相似
+Upstream 的配置可以被直接绑定在指定 `Route` 中，也可以被绑定在 `Service` 中，不过 `Route`
中的配置优先级更高。这里的优先级行为与 `Plugin` 非常相似
### 配置参数
diff --git a/docs/zh/latest/plugin-develop.md b/docs/zh/latest/plugin-develop.md
index d2babce..1ef7c5c 100644
--- a/docs/zh/latest/plugin-develop.md
+++ b/docs/zh/latest/plugin-develop.md
@@ -53,9 +53,7 @@ nginx_config:
插件本身提供了 init 方法。方便插件加载后做初始化动作。
-注：如果部分插件的功能实现，需要在 Nginx 初始化启动，则可能需要在 __apisix/init.lua__ 文件的初始化方法 http_init
中添加逻辑，并且
-可能需要在 __apisix/cli/ngx_tpl.lua__ 文件中，对 Nginx
配置文件生成的部分，添加一些你需要的处理。但是这样容易对全局产生影响，根据现有的
-插件机制，**我们不建议这样做，除非你已经对代码完全掌握**。
+注：如果部分插件的功能实现，需要在 Nginx 初始化启动，则可能需要在 __apisix/init.lua__ 文件的初始化方法 http_init
中添加逻辑，并且可能需要在 __apisix/cli/ngx_tpl.lua__ 文件中，对 Nginx
配置文件生成的部分，添加一些你需要的处理。但是这样容易对全局产生影响，根据现有的插件机制，**我们不建议这样做，除非你已经对代码完全掌握**。
## 插件命名，优先级和其他
@@ -123,8 +121,7 @@ local _M = {
## 配置描述与校验
-定义插件的配置项，以及对应的 [JSON Schema](https://json-schema.org) 描述，并完成对 JSON
的校验，这样方便对配置的数据规
-格进行验证，以确保数据的完整性以及程序的健壮性。同样，我们以 example-plugin 插件为例，看看他的配置数据：
+定义插件的配置项，以及对应的 [JSON Schema](https://json-schema.org) 描述，并完成对 JSON
的校验，这样方便对配置的数据规格进行验证，以确保数据的完整性以及程序的健壮性。同样，我们以 example-plugin 插件为例，看看他的配置数据：
```json
{
diff --git a/docs/zh/latest/router-radixtree.md
b/docs/zh/latest/router-radixtree.md
index ff2dbde..546258f 100644
--- a/docs/zh/latest/router-radixtree.md
+++ b/docs/zh/latest/router-radixtree.md
@@ -194,8 +194,7 @@ apisix:
### 如何通过 Nginx 内置变量过滤路由
-具体参数及使用方式请查看 [radixtree#new](https://github.com/api7/lua-resty-radixtree#new)
文档
-，下面是一个简单的示例:
+具体参数及使用方式请查看 [radixtree#new](https://github.com/api7/lua-resty-radixtree#new)
文档，下面是一个简单的示例:
```shell
$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
diff --git a/docs/zh/latest/stand-alone.md b/docs/zh/latest/stand-alone.md
index 5821fa9..07f7425 100644
--- a/docs/zh/latest/stand-alone.md
+++ b/docs/zh/latest/stand-alone.md
@@ -28,16 +28,14 @@ title: Stand-alone mode
1. kubernetes(k8s)：声明式 API 场景，通过全量 yaml 配置来动态更新修改路由规则。
2. 不同配置中心：配置中心的实现有很多，比如 Consul 等，使用全量 yaml 做中间转换桥梁。
-APISIX 节点服务启动后会立刻加载 `conf/apisix.yaml` 文件中的路由规则到内存，并且每间隔一定时间
-（默认 1 秒钟），都会尝试检测文件内容是否有更新，如果有更新则重新加载规则。
+APISIX 节点服务启动后会立刻加载 `conf/apisix.yaml` 文件中的路由规则到内存，并且每间隔一定时间（默认 1
秒钟），都会尝试检测文件内容是否有更新，如果有更新则重新加载规则。
*注意*：重新加载规则并更新时，均是内存热更新，不会有工作进程的替换过程，是个热更新过程。
由于目前 Admin API 都是基于 etcd 配置中心解决方案，当开启 Stand-alone 模式后，
Admin API 将不再被允许使用。
-通过设置 `conf/config.yaml` 中的 `apisix.config_center` 选项为 `yaml` ，并禁用 Admin API 即可启
-用 Stand-alone 模式。
+通过设置 `conf/config.yaml` 中的 `apisix.config_center` 选项为 `yaml` ，并禁用 Admin API
即可启用 Stand-alone 模式。
参考下面示例：
diff --git a/utils/fix-zh-doc-segment.py b/utils/fix-zh-doc-segment.py
new file mode 100755
index 0000000..da0ccf6
--- /dev/null
+++ b/utils/fix-zh-doc-segment.py
@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+# coding: utf-8
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You 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.
+#
+import os
+from os import path
+from zhon.hanzi import punctuation # sudo pip3 install zhon
+
+
+def need_fold(pre, cur):
+ pre = pre.rstrip("\r\n")
+ if len(pre) == 0 or len(cur) == 0:
+ return False
+ if ord(pre[-1]) < 128 or ord(cur[0]) < 128:
+ return False
+ # the prev line ends with Chinese and the curr line starts with Chinese
+ if pre.startswith(":::note"):
+ # ignore special mark
+ return False
+ if pre[-1] in punctuation:
+ # skip punctuation
+ return False
+ return True
+
+def check_segment(root):
+ for parent, dirs, files in os.walk(root):
+ for fn in files:
+ fn = path.join(parent, fn)
+ with open(fn) as f:
+ lines = f.readlines()
+ new_lines = [lines[0]]
+ for i in range(1, len(lines)):
+ if need_fold(lines[i-1], lines[i]):
+ new_lines[-1] = new_lines[-1].rstrip("\r\n") + lines[i]
+ else:
+ new_lines.append(lines[i])
+ if len(new_lines) != len(lines):
+ print("find broken newline in file: %s" % fn)
+ with open(fn, "w") as f:
+ f.writelines(new_lines)
+
+
+roots = ["docs/zh/latest/"]
+for r in roots:
+ check_segment(r)
