From 02c6eb7d5f365d6e3f9a76150c37b575c5a53c44 Mon Sep 17 00:00:00 2001 From: Tink_Y <31891223+tink2123@users.noreply.github.com> Date: Thu, 18 Oct 2018 15:06:42 +0800 Subject: [PATCH] Update write_docs_cn.md --- doc/v2/dev/write_docs_cn.md | 92 ++++++++++++++++++++++++++----------- 1 file changed, 64 insertions(+), 28 deletions(-) diff --git a/doc/v2/dev/write_docs_cn.md b/doc/v2/dev/write_docs_cn.md index 394b8281c..211254039 100755 --- a/doc/v2/dev/write_docs_cn.md +++ b/doc/v2/dev/write_docs_cn.md @@ -83,16 +83,13 @@ pip install -r requirements.txt --models /external/models \ --mobile /external/mobile ``` -然后： - - -打开浏览器并导航到http://localhost:8000。 +然后：打开浏览器并导航到http://localhost:8000。 >*网站可能需要几秒钟才能成功加载，因为构建需要一定的时间* >*如果您是在docker环境下运行的这些步骤，请检查ip确保可以将端口8000映射到您的主机* -## 预览新文档或更新API +## 贡献新文档或更新API 所有内容都应该以[Markdown](https://guides.github.com/features/mastering-markdown/) (GitHub风格)的形式编写(尽管在文档中有一些使用.rst格式的遗留内容)。 @@ -101,63 +98,102 @@ pip install -r requirements.txt - 在你开始写作之前，我们建议你回顾一下这些关于贡献内容的指南 + --- + **贡献新文档** - --- - 创建一个新的` .md` 文件或者在您当前操作的仓库中修改已存在的文章 - 将新增的文档名，添加到对应的index文件中 + --- + **贡献或修改Python API** - --- - 在将要重新编译代码的docker容器内或主机的对应位置： + + 在编译代码的docker容器内,或主机的对应位置： - 运行脚本 `paddle/scripts/paddle_build.sh`(在 Paddle repo 下) - - **或者** （如果您想理解这一过程）： - - - 在`Paddle` 仓库下创建一个新的文件夹用来编译文档，可以命名为`build` - - 在这个新文件夹下，运行下列`cmake`和`make`命令去构建新的PaddlePaddle： + + ```bash + # 编译paddle的python库 + cd Paddle + ./paddle/scripts/paddle_docker_build.sh gen_doc_lib full + cd .. + ``` + + - 运行预览工具 + + ``` + # 在编译paddle的对应docker镜像中运行预览工具 + + docker run -it -v /Users/xxxx/workspace/paddlepaddle_workplace:/workplace -p 8000:8000 [images_id] /bin/bash + ``` + + > 其中`/Users/xxxx/workspace/paddlepaddle_workplace`请替换成您本机的paddle工作环境，`/workplace`请替换成您相应的 docker 下的工作环境，这一映射会保证我们同时完成编译python库、修改FluidDoc和使用预览工具。 + + > [images_id]为docker中您使用的paddlepaddle的镜像id。 + + - 设置环境变量 - ``` - cmake .. -DCMAKE_BUILD_TYPE=Release -DWITH_DOC=ON -DWITH_GPU=OFF -DWITH_MKL=OFF -DWITH_FLUID_ONLY=ON + ``` + # 在docker环境中 + # 设置环境变量`PYTHONPATH`使预览工具可以找到 paddle 的 python 库 + export PYTHONPATH=/workplace/Paddle/build/python/ + ``` - # You may replace `nproc` with the number of processor cores your system can offer for the build. - make -j `nproc` gen_proto_py framework_py_proto copy_paddle_pybind paddle_python - ``` + - 清理旧文件 - - 设置环境变量`PYTHONPATH`去包含这个`build`（或任意其他您设置的名字）目录 + ``` + # 清除历史生成的文件，如果是第一次使用预览工具可以跳过这一步 + rm -rf /workplace/FluidDoc/doc/fluid/menu.json /workplace/FluidDoc/doc/fluid/api/menu.json /tmp/docs/ /tmp/api/ + ``` - 需要注意的是：如果您使用的是 Docker，`paddle_docker_build.sh`会构建一个新的 Docker 容器。这将破坏当前 Docker 下的 PaddlePaddle.org 安装，因此如果您想预览文档，不推荐您用这种方式编译代码。 + - 启动预览工具 + ``` + cd /workplace/PaddlePaddle.org/portal + pip install -r requirements.txt + ./runserver --paddle /workplace/FluidDoc/ + ``` + +--- + **预览修改** - --- + + + 打开浏览器并导航到http://localhost:8000。 + 在要更新的页面上，单击右上角的Refresh Content + + 进入使用文档单元后，API部分并不包含内容，希望预览API文档需要点击API目录，几分钟后您将看到生成的 API reference。 + ## 提交修改 -如果您希望修改代码，请在`Paddle`仓库下执行下列步骤。 +如果您希望修改代码，请在`Paddle`仓库下参考[如何贡献代码]()执行操作。 如果您仅修改文档： - - 若修改的内容在`doc`文件夹内，您只需要在`FluidDoc`仓库下提交`PR` + - 修改的内容在`doc`文件夹内，您只需要在`FluidDoc`仓库下提交`PR` - - 若您修改的内容在`external`文件夹内： + - 修改的内容在`external`文件夹内： - 1.在您修改的仓库下提交PR，`FluidDoc`仓库只是一个包装器，将其他仓库的链接（git术语的“submodule”）集合在了一起。 + 1.在您修改的仓库下提交PR。这是因为：`FluidDoc`仓库只是一个包装器，将其他仓库的链接（git术语的“submodule”）集合在了一起。 2.当您的修改被认可后，更新FluidDoc中对应的`submodule`到源仓库最新的commit-id。 - > 例如，您更新了book仓库中的文档： + > 例如，您更新了book仓库中的develop分支下的文档： - > - 进入`book`目录 - > - 切换到你想更新到的commit-id + + > - 进入`FluidDoc/external/book`目录 + > - 更新 commit-id 到最新的提交：`git pull origin develop` > - 在`FluidDoc`中提交你的修改 3.在`FluidDoc`仓库下为您的修改提交PR -提交PR的步骤可以参考[如何贡献代码](../development/contribute_to_paddle.html) +提交修改与PR的步骤可以参考[如何贡献代码](../development/contribute_to_paddle.html) ## 帮助改进预览工具 -- GitLab