Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

【Docs 文档吐槽大会】中文文档的书写 #6462

Open
megemini opened this issue Jan 10, 2024 · 2 comments
Open

【Docs 文档吐槽大会】中文文档的书写 #6462

megemini opened this issue Jan 10, 2024 · 2 comments
Labels
PFCC Paddle Framework Contributor Club,https://github.com/PaddlePaddle/community/tree/master/pfcc

Comments

@megemini
Copy link
Contributor

megemini commented Jan 10, 2024

文档链接&描述 Document Links & Description

中文文档书写时,遇到几个问题:

  1. 一个文档可能涉及多个地方的修改,如 xxx_cn.rst, Overview_cn.rst(又可能存在多级), Tensor_cn.rst, pytorch_api_mapping_cn.rst 等,一不小心就遗漏了。
    建议:在《文档贡献指南》中增加引导,在哪里增加的 api,需要对应 增加/修改 哪些中文文档。或者,只需要开发者添加中文文档,文档结构由工具根据英文文档生成,从而保持一致性。

  2. Tensor_cn.rst 书写不规范,仍存在第一个 Tensor 参数,如:

multi_dot(x, name=None)
:::::::::

建议:增加参数检查,或者由工具根据中英文文档自动生成,并删除第一个参数。

  1. pytorch_api_mapping_cn.rst 太乱了,有的还要写编号,有的 api 要写多个地方。

建议:重构,并增加不同类型书写指导,如,“仅参数名不同”:表示xxx,“参数不同”:表示xxx

补充:pfcc 的 blog 中增加类似“周报”/“研发通报”的专栏,及时拉平飞桨内部研发与开源社区的信息差,作为官方文档之外的补充,及时通告,如,某关键 PR 需要合入,会影响xxx。

请提出你的建议/提个PR修复这个问题 Please give your suggestion/update a PR to fix it

No response

@paddle-bot paddle-bot bot added the PFCC Paddle Framework Contributor Club,https://github.com/PaddlePaddle/community/tree/master/pfcc label Jan 10, 2024
@sunzhongkai588
Copy link
Collaborator

增加参数检查

顺师傅,我挖坟的时候突然发现,好像是有参数检查的脚本的.. check_api_parameters.sh

但不知道为啥给关了 #4808

check_parameters=OFF
if [ "${check_parameters}" = "OFF" ] ; then
#echo "chinese api doc fileslist is empty, skip check."
echo "check_api_parameters is not stable, close it temporarily."

@megemini
Copy link
Contributor Author

单从 /home/shun/Documents/Projects/paddle/megemini/paddle_docs/ci_scripts/check_api_parameters.pycheck_api_parameters 来看,里面的 regex 好像检查不了 Tensor_cn.rst 里面的方法 ... ...

PR 只说了 not stable,也没说具体什么问题,不太清楚了 ~

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
PFCC Paddle Framework Contributor Club,https://github.com/PaddlePaddle/community/tree/master/pfcc
Projects
None yet
Development

No branches or pull requests

2 participants