PaddlePaddle / PaddlePaddle/docs

文档构建会导致 git 仓库产生大量文件改动

Open
#6,232 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

PFCC
Dominant language
Python
Stars
284
Forks
906
PR merge metrics
No merged PRs in 30d

Description

文档链接&描述 Document Links & Description

按照教程构建文档后,将产生大约 10000+ 改动的文件。

其中:

  • 绝大多数是 output/ 新增,由于该路径未位于 .gitignore 中,因此未忽略;
  • 大约 1400 项是英文文档部分,该部分动态生成得到;
  • 大约 300 项来自 docs/api/paddle/*_cn.rstCOPY-FROM 块的更新
  • 其余约 200 项为 docs/practicesdocs/guides 中,ipynb 被移除,构建为新增的 mdpng

这部分的构建后改动会导致每次构建破坏原有的仓库文件信息,从而不利于在开发文档时构建测试。

在更极端情况中,如果进行修改后,未提交更改就进行了构建,则其修改内容很可能被覆盖或丢失,从而增加修改成本。

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

对于 output 与英文文档部分,已添加 gitignore 解决 #6231
其余中文文档更新与 ipynb 部分,尚未解决,或许需要添加临时目录以供构建等,如添加 build 目录,复制所有要改动的文件到其中完成改动。

附1 构建命令不明确:README 教程中的构建指引,采用 bash docs-build.sh -f absolute_path_docs 方法,略显不直观,能否考虑基于 docs-build.sh 计算路径,或使用 pwd 等方法直接获取,避免这里造成不确定填 <PROJECT_ROOT>/docs 还是 <PROJECT_ROOT>

附2 权限非预期:构建过程由于基于 docker 进行,生成的文件都是 root 用户所有的,导致低权限状态下无法修改、删除相关文件

附3 临时绕开文件变动方法

rm -rf output/ docs/api/paddle/ docs/guides/ docs/inference_api/ docs/practices/  # 需要 root 权限
git reset HEAD --hard

@sunzhongkai588 @SigureMo

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with docs-build.sh and the README build instructions, then inspect how output/, docs/api/paddle/*_cn.rst, docs/practices, docs/guides, and docs/inference_api/ are handled. Check the existing .gitignore change from #6231 and the Docker invocation. Done should mean a documentation build does not create or overwrite tracked files unexpectedly and does not leave generated files owned by root.

Written by the indexing model from the issue text.

Assessment

Tech stack
bash, docker
Domain
build-system, devops, documentation
Issue type
Bug
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.