Merge branch 'develop' of https://github.com/PaddlePaddle/docs into feature/my-cool-stuff

Author: xxiu1

.github/workflows/preview-url-comment.yml

@@ -0,0 +1,58 @@
+name: Comment Preview URLs
+
+on:
+  workflow_run:
+    workflows: ["Generate Preview URLs"]
+    types:
+      - completed
+
+jobs:
+  comment:
+    name: Post Preview URLs Comment
+    runs-on: ubuntu-latest
+    if: >
+      github.event.workflow_run.event == 'pull_request' &&
+      github.event.workflow_run.conclusion == 'success'
+    permissions:
+      pull-requests: write
+
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          run-id: ${{ github.event.workflow_run.id }}
+
+      - name: Read PR metadata
+        id: pr-metadata
+        run: |
+          PR_NUMBER=$(find . -name "pr_number.txt" -exec cat {} \;)
+          PR_SHA=$(find . -name "pr_sha.txt" -exec cat {} \;)
+          echo "pr_number=$PR_NUMBER" >> $GITHUB_OUTPUT
+          echo "pr_sha=$PR_SHA" >> $GITHUB_OUTPUT
+
+      - name: Read preview URLs
+        id: preview-urls
+        run: |
+          PREVIEW_CONTENT=$(find . -name "preview_urls.txt" -exec cat {} \;)
+          {
+            echo 'content<<EOF'
+            echo "$PREVIEW_CONTENT"
+            echo EOF
+          } >> $GITHUB_OUTPUT
+
+      - name: Find existing comment
+        uses: peter-evans/find-comment@v4
+        id: fc
+        with:
+          issue-number: ${{ steps.pr-metadata.outputs.pr_number }}
+          comment-author: 'github-actions[bot]'
+          body-includes: '本次 PR 文档预览链接'
+
+      - name: Create or update comment
+        uses: peter-evans/create-or-update-comment@v4
+        with:
+          comment-id: ${{ steps.fc.outputs.comment-id }}
+          issue-number: ${{ steps.pr-metadata.outputs.pr_number }}
+          body: ${{ steps.preview-urls.outputs.content }}
+          edit-mode: replace

.github/workflows/preview-url-generate.yml

@@ -0,0 +1,52 @@
+name: Generate Preview URLs
+
+on:
+  pull_request:
+    branches: ["develop"]
+    paths:
+      - 'docs/**.rst'
+      - 'docs/**.md'
+
+jobs:
+  generate-urls:
+    name: Generate Preview URLs
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout PR branch
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Fetch base branch
+        run: |
+          git fetch origin develop:develop
+
+      - name: Generate preview URLs
+        id: generate
+        run: |
+          chmod +x ci_scripts/report_preview_url.sh
+          ./ci_scripts/report_preview_url.sh ${{ github.event.pull_request.number }} > preview_urls.txt
+
+      - name: Upload preview URLs as artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: preview-urls-${{ github.event.pull_request.number }}
+          path: preview_urls.txt
+          retention-days: 1
+
+      - name: Save PR metadata
+        run: |
+          echo "${{ github.event.pull_request.number }}" > pr_number.txt
+          echo "${{ github.event.pull_request.head.sha }}" > pr_sha.txt
+
+      - name: Upload PR metadata
+        uses: actions/upload-artifact@v4
+        with:
+          name: pr-metadata-${{ github.event.pull_request.number }}
+          path: |
+            pr_number.txt
+            pr_sha.txt
+          retention-days: 1

ci_scripts/check_api_label_cn.py

@@ -23,7 +23,7 @@
 # check file's api_label
 def check_api_label(rootdir, file):
     real_file = Path(rootdir) / file
-    with open(real_file, "r", encoding="utf-8") as f:
+    with real_file.open("r", encoding="utf-8") as f:
         first_line = f.readline().strip()
     return first_line == generate_en_label_by_path(file)
 
@@ -53,13 +53,13 @@ def find_all_api_labels_in_dir(rootdir):
 # api_labels in a file
 def find_api_labels_in_one_file(file_path):
     api_labels_in_one_file = []
-    with open(file_path, "r", encoding="utf-8") as f:
+    with file_path.open("r", encoding="utf-8") as f:
         lines = f.readlines()
         for line in lines:
-            line = re.search(".. _([a-zA-Z0-9_]+)", line)
-            if not line:
+            match = re.search(".. _([a-zA-Z0-9_]+)", line)
+            if not match:
                 continue
-            api_labels_in_one_file.append(line.group(1))
+            api_labels_in_one_file.append(match.group(1))
     return api_labels_in_one_file
 
 
@@ -84,7 +84,7 @@ def run_cn_api_label_checking(rootdir, files):
     for file in files:
         if not file.endswith(".rst"):
             continue
-        with open(Path(rootdir) / file, "r", encoding="utf-8") as f:
+        with (Path(rootdir) / file).open("r", encoding="utf-8") as f:
             pattern = f.read()
         matches = re.findall(r":ref:`([^`]+)`", pattern)
         for match in matches:

ci_scripts/check_api_label_cn.sh

@@ -13,7 +13,7 @@ if [ -z ${BRANCH} ]; then
     BRANCH="develop"
 fi
 
-all_git_files=`git diff --name-only --diff-filter=ACMR upstream/${BRANCH} | sed 's#docs/##g'`
+all_git_files=`git diff --name-only --diff-filter=ACMR upstream/${BRANCH} | sed 's#^docs/##'`
 echo $all_git_files
 echo "Run API_LABEL Checking"
 python check_api_label_cn.py ${DOCROOT} ${APIROOT} $all_git_files

ci_scripts/report_preview_url.sh

@@ -0,0 +1,42 @@
+#!/bin/bash
+
+pr_id="$1"
+
+if [ -z "$pr_id" ]; then
+    echo "Error: Pull Request ID is not provided."
+    exit 1
+fi
+
+generate_preview_url() {
+    local file_path="$1"
+    local pr_id="$2"
+    local path_no_ext="${file_path%.*}"
+    local base_url="http://preview-pr-${pr_id}.paddle-docs-preview.paddlepaddle.org.cn/documentation/docs/zh/"
+    local final_url="${base_url}${path_no_ext}.html"
+    echo "$final_url"
+}
+
+mapfile -t all_git_files < <(git diff --name-only --diff-filter=ACMR develop | sed 's#^docs/##')
+
+output_lines=()
+
+for file in "${all_git_files[@]}"; do
+    if [[ "$file" == *.rst || "$file" == *.md ]]; then
+        url=$(generate_preview_url "$file" "$pr_id")
+        output_lines+=("- \`docs/${file}\`: [点击预览](${url})")
+    fi
+done
+
+
+if [ ${#output_lines[@]} -gt 0 ]; then
+    cat <<-EOF
+<details>
+<summary>📚 本次 PR 文档预览链接 (点击展开)</summary>
+
+以下是本次 PR 中变更文档的预览链接：
+
+$(printf '%s\n' "${output_lines[@]}")
+
+</details>
+EOF
+fi

docs/api/paddle/distributed/fleet/DistributedStrategy_cn.rst

@@ -232,7 +232,7 @@ COPY-FROM: paddle.distributed.fleet.DistributedStrategy.amp_configs
 dgc
 '''''''''
 
-是否启用深度梯度压缩训练。更多信息请参考[Deep Gradient Compression](https://arxiv.org/abs/1712.01887)。默认值：False
+是否启用深度梯度压缩训练。更多信息请参考 `Deep Gradient Compression https://arxiv.org/abs/1712.01887`_ 。默认值：False
 
 **代码示例**
 
@@ -267,7 +267,7 @@ COPY-FROM: paddle.distributed.fleet.DistributedStrategy.fp16_allreduce
 sharding
 '''''''''
 
-是否开启 sharding 策略。sharding 实现了[ZeRO: Memory Optimizations Toward Training Trillion Parameter Models](https://arxiv.org/abs/1910.02054)
+是否开启 sharding 策略。sharding 实现了 `ZeRO: Memory Optimizations Toward Training Trillion Parameter Models https://arxiv.org/abs/1910.02054`_
 中 ZeRO-DP 类似的功能，其通过将模型的参数和优化器状态在 ranks 间分片来支持更大模型的训练。
 
 目前在混合并行(Hybrid parallelism) 模式下，sharding config 作为混合并行设置的统一入口来设置混合并行相关参数。

docs/api/paddle/distributed/fleet/UtilBase_cn.rst

@@ -9,43 +9,43 @@ UtilBase
 方法
 ::::::::::::
 all_reduce(input, mode="sum", comm_world="worker")
-'''''''''
+''''''''''''''''''''''''''''''''''''''''''''''''''
 在指定的通信集合间进行归约操作，并将归约结果返回给集合中每个实例。
 
 **参数**
 
     - **input** (list|tuple|numpy.array) – 归约操作的输入。
     - **mode** (str) - 归约操作的模式，包含求和，取最大值和取最小值，默认为求和归约。
-    - **comm_world** (str) - 归约操作的通信集合，包含：server 集合(``server``)，worker 集合(``worker``)及所有节点集合(``all``)，默认为 worker 集合。
+    - **comm_world** (str) - 归约操作的通信集合，包含：server 集合 (``server``)，worker 集合 (``worker``) 及所有节点集合 (``all``)，默认为 worker 集合。
 
 **返回**
 
-Numpy.array|None：一个和``input``形状一致的 numpy 数组或 None。
+Numpy.array|None：一个和 ``input`` 形状一致的 numpy 数组或 None。
 
 **代码示例**
 
 COPY-FROM: paddle.distributed.fleet.UtilBase.all_reduce
 
 barrier(comm_world="worker")
-'''''''''
+''''''''''''''''''''''''''''
 在指定的通信集合间进行阻塞操作，以实现集合间进度同步。
 
 **参数**
 
-   - **comm_world** (str) - 阻塞操作的通信集合，包含：server 集合(``server``)，worker 集合(``worker``)及所有节点集合(``all``)，默认为 worker 集合。
+   - **comm_world** (str) - 阻塞操作的通信集合，包含：server 集合 (``server``)，worker 集合 (``worker``) 及所有节点集合 (``all``)，默认为 worker 集合。
 
 **代码示例**
 
 COPY-FROM: paddle.distributed.fleet.UtilBase.barrier
 
 all_gather(input, comm_world="worker")
-'''''''''
+''''''''''''''''''''''''''''''''''''''''
 在指定的通信集合间进行聚合操作，并将聚合的结果返回给集合中每个实例。
 
 **参数**
 
    - **input** (int|float) - 聚合操作的输入。
-   - **comm_world** (str) - 聚合操作的通信集合，包含：server 集合(``server``)，worker 集合(``worker``)及所有节点集合(``all``)，默认为 worker 集合。
+   - **comm_world** (str) - 聚合操作的通信集合，包含：server 集合 (``server``)，worker 集合 (``worker``) 及所有节点集合 (``all``)，默认为 worker 集合。
 
 **返回**
 
@@ -56,7 +56,7 @@ all_gather(input, comm_world="worker")
 COPY-FROM: paddle.distributed.fleet.UtilBase.all_gather
 
 get_file_shard(files)
-'''''''''
+'''''''''''''''''''''
 在数据并行的分布式训练中，获取属于当前训练节点的文件列表。
 
 .. code-block:: text
@@ -77,8 +77,7 @@ get_file_shard(files)
 COPY-FROM: paddle.distributed.fleet.UtilBase.get_file_shard
 
 print_on_rank(message, rank_id)
-'''''''''
-
+'''''''''''''''''''''''''''''''''
 在编号为 `rank_id` 的节点上打印指定信息。
 
 **参数**