refactor(docs): refactor URL parsing module in pytorch mapping doc #7701
+374
−387
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
* Split the monolithic `utils.py` into a modular `utils/` package structure. * Add `api_url_parser.py` to implement a unified URL parser for PyTorch and Paddle APIs using `sphobjinv`. * Update import paths in scripts like `generate_pytorch_api_mapping.py` to adapt to the new module structure. * Remove duplicate Tensor API entries (`clear_gradient`, `clone`, `data_ptr`) from the documentation. * Improve `extract_no_need_convert_list` to support both `api_mapping.json` and `attribute_mapping.json`.
LittleHeroZZZX
requested review from
Echo-Nie,
jzhang533,
mattheliu,
ooooo-create and
sunzhongkai588
as code owners
|
感谢你贡献飞桨文档，文档预览构建中，Docs-New 跑完后即可预览，预览链接：http://preview-pr-7701.paddle-docs-preview.paddlepaddle.org.cn/documentation/docs/zh/api/index_cn.html |
📚 本次 PR 文档预览链接（点击展开）
|
Contributor
There was a problem hiding this comment.
Pull request overview
本 PR 重构了 PyTorch→Paddle API 映射文档工具中 API 文档链接的获取方式，引入基于 Sphinx objects.inv 的 URL 解析器，并将原 utils.py 拆分为包结构以便扩展维护。
Changes:
- 将部分 API URL 生成逻辑重构为基于 Sphinx inventory（
objects.inv）解析，新增api_url_parser模块 - 将
tools/utils.py拆分为tools/utils/包，并更新相关脚本的导入路径 - 调整
validate_pytorch_api_mapping.py默认映射文档路径为相对路径；同时修改了Tensor__upper_cn.rst的部分章节内容
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/guides/model_convert/convert_from_pytorch/tools/validate_pytorch_api_mapping.py | 默认映射文档路径由硬编码绝对路径改为基于 __file__ 的相对路径。 |
| docs/guides/model_convert/convert_from_pytorch/tools/validate_api_difference_consistency.py | 更新工具函数导入路径以匹配新的 utils/ 包结构。 |
| docs/guides/model_convert/convert_from_pytorch/tools/generate_pytorch_api_mapping.py | 更新工具函数导入路径，间接接入新的 URL 解析能力。 |
| docs/guides/model_convert/convert_from_pytorch/tools/utils/utils.py | 新的工具函数集合，新增通过 parser 获取 Torch/Paddle API URL 的入口。 |
| docs/guides/model_convert/convert_from_pytorch/tools/utils/api_url_parser.py | 新增：从 Sphinx inventory 解析 API→URL 的核心实现（Torch/Paddle）。 |
| docs/guides/model_convert/convert_from_pytorch/tools/utils/init.py | 新增：utils 包导出定义。 |
| docs/guides/model_convert/convert_from_pytorch/tools/utils.py | 删除：原单文件工具库。 |
| docs/api/paddle/Tensor__upper_cn.rst | 删除/调整若干 Tensor API 小节内容（与工具重构并列出现在同一 PR）。 |
Comment on lines
364
to
368
|
|
||
|
|
||
| clone() | ||
| ::::::::: | ||
|
|
||
| 返回：克隆的新的 Tensor | ||
|
|
||
| 返回类型：Tensor | ||
|
|
||
| **代码示例** | ||
| COPY-FROM: paddle.Tensor.clone | ||
|
|
||
|
|
||
|
|
||
| retain_grads() |
There was a problem hiding this comment.
该 PR 描述主要是重构差异文档工具的 URL 解析方式，但这里同时删除了 Tensor API 文档中的若干小节（如 clone() 相关内容）。这会影响生成的 API 文档与 objects.inv 内容，建议在 PR 描述里补充此处改动的动机/关联性，避免后续维护者误解为无关修改。
Comment on lines
364
to
368
|
|
||
|
|
||
| clone() | ||
| ::::::::: | ||
|
|
||
| 返回：克隆的新的 Tensor | ||
|
|
||
| 返回类型：Tensor | ||
|
|
||
| **代码示例** | ||
| COPY-FROM: paddle.Tensor.clone | ||
|
|
||
|
|
||
|
|
||
| retain_grads() |
There was a problem hiding this comment.
这里删除了 clone() 小节（原内容包含 COPY-FROM: paddle.Tensor.clone 示例）。目前文件后文仍保留另一份 clone() 文档且示例为手写代码，删除这段会导致示例不再通过 COPY-FROM 与英文 docstring 同步。建议保留单一入口并优先使用 COPY-FROM 的示例（必要时删去后文重复小节或把后文示例改为 COPY-FROM）。
Comment on lines
449
to
453
|
|
||
|
|
||
| data_ptr() | ||
| ::::::::: | ||
|
|
||
| 返回：返回本 Tensor 第一个元素的数据地址。 | ||
|
|
||
| 返回类型：int | ||
|
|
||
| **代码示例** | ||
| COPY-FROM: paddle.Tensor.data_ptr | ||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
| get_strides() |
There was a problem hiding this comment.
这里删除了 data_ptr() 小节及其 COPY-FROM: paddle.Tensor.data_ptr 示例；当前文件后文仍存在 data_ptr() 说明，但已不包含“代码示例/COPY-FROM”，会导致该 API 的示例缺失且与仓库 API 文档规范不一致。建议将示例保留并合并到唯一的 data_ptr() 小节中（优先 COPY-FROM）。
docs/guides/model_convert/convert_from_pytorch/tools/utils/api_url_parser.py
Show resolved
Hide resolved
docs/guides/model_convert/convert_from_pytorch/tools/utils/api_url_parser.py
Show resolved
Hide resolved
docs/guides/model_convert/convert_from_pytorch/tools/utils/api_url_parser.py
Outdated
Show resolved
Hide resolved
docs/guides/model_convert/convert_from_pytorch/tools/utils/api_url_parser.py
Show resolved
Hide resolved
| try: | ||
| relative_path = os.path.relpath(local_path, base_dir) | ||
| return f"https://github.com/PaddlePaddle/docs/tree/develop/docs/guides/model_convert/convert_from_pytorch/{relative_path}" | ||
| except: |
There was a problem hiding this comment.
Except block directly handles BaseException.
Suggested change
| except: | |
| except Exception: |
- Replace `get_pytorch_url` and `get_paddle_url` with unified `get_url` function - Add `get_url` to utils module exports for broader accessibility - Simplify URL retrieval logic in mapping table generators - Ensure consistent handling of escaped underscores across all API names
zhwesky2010
reviewed
Jan 28, 2026
docs/guides/model_convert/convert_from_pytorch/tools/validate_api_difference_consistency.py
Outdated
Show resolved
Hide resolved
- Rename utils.py to api_utils.py for better clarity of its purpose - Update __init__.py to expose all utility functions from api_utils - Adjust import statements in dependent scripts to use the new module structure - Maintains all existing functionality while improving code organization
zhwesky2010
changed the title
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
本 PR 重构差异文档目录生成工具（产物
pytorch_api_mapping_cn.md）中获取 Paddle 和 Torch API 的方式。由原本的硬编码规则修改为从 Sphinx 的编译产物直接获取，url 链接准确率更高且可以有效规避 URL 不存在的问题。缺失文档的 API 列表