如何贡献文档

    Paddle的文档主要分为以下几个模块：

    • 新手入门：包括安装说明、深度学习基础知识、学习资料等，旨在帮助用户快速安装和入门；
    • 使用指南：包括数据准备、网络配置、训练、Debug、预测部署和模型库文档，旨在为用户提供PaddlePaddle基本用法讲解；
    • 进阶使用：包括服务器端和移动端部署、如何贡献代码/文档、如何性能调优等，旨在满足开发者的需求；

    我们的文档支持reStructured Text和 (GitHub风格)格式的内容贡献。

    撰写文档完成后，您可以使用预览工具查看文档在官网显示的效果，以验证您的文档是否能够在官网正确显示。

    如果您正在修改代码文档（即API），并在Docker容器中使用PaddlePaddle，请在您相应的docker容器中执行下列步骤。因为API的文档生成器依赖于PaddlePaddle。

    如果您只改进了文本/媒体内容(不需要安装或构建PaddlePaddle)，或者正在主机上构建PaddlePaddle，请继续在主机上执行下列步骤。

    首先下载完整的文档存储仓库，其中会同步更新FluidDoc中的submodule（所有的submodule均在FluidDoc/external中），以保证所有文档可以正常显示：

    其他可拉取的存储库有：

    1. git clone https://github.com/PaddlePaddle/book.git
    2. git clone https://github.com/PaddlePaddle/models.git
    3. git clone https://github.com/PaddlePaddle/Mobile.git

    您可以将这些本地副本放在电脑的任意目录下，稍后我们会在启动 PaddlePaddle.org时指定这些仓库的位置。

    在此之前，请确认您的操作系统安装了python的依赖项

    以ubuntu系统为例，运行：

    1. sudo apt-get update && apt-get install -y python-dev build-essential

    然后：

    1. cd PaddlePaddle.org/portal

    之后需要安装依赖库，请确保在python 2.7.15 或2.7.16 环境下安装。推荐使用Anaconda或virtualenv创建合适的虚拟环境后安装依赖库。

    可选项：如果你希望实现中英网站转换，以改善PaddlePaddle.org，请安装GNU gettext

    添加您希望加载和构建内容的目录列表(选项包括：—paddle，—book，—models，—mobile)

    运行：

    1. ./runserver --paddle <path_to_FluidDoc_dir>

    注意： 为第一步中paddle副本在您本机的存储地址。

    如果您需要处理依赖于book、models或mobile存储库内容的文档，您可以添加一个或多个可选项：

    1. ./runserver --paddle <path_to_fluiddoc_dir> \
    2.     --book <path_to_fluiddoc_dir>/external/book \
    3.     --models <path_to_fluiddoc_dir>/external/models \
    4.     --mobile <path_to_fluiddoc_dir>/external/mobile

    然后：打开浏览器并导航到

    如果您是在docker环境下运行的这些步骤，请检查ip确保可以将端口8000映射到您的主机

    所有内容都应该以Markdown (GitHub风格)的形式编写(尽管在文档中有一些使用.rst格式的遗留内容)。

    在完成安装步骤后，您还需要完成下列操作：

    • 在你开始写作之前，我们建议你回顾一下这些关于贡献内容的指南

    贡献新文档

    • 创建一个新的 .md 文件或者在您当前操作的仓库中修改已存在的文章
    • 将新增的文档名，添加到对应的index文件中

    贡献或修改Python API

    在编译代码的docker容器内,或主机的对应位置：

    • 运行脚本 (在 Paddle repo 下) 
    1. # 编译paddle的python库
    2. cd Paddle
    3. ./paddle/scripts/paddle_docker_build.sh gen_doc_lib full
    4. cd ..
    • 运行预览工具
    [images_id]为docker中您使用的paddlepaddle的镜像id。
    1. # 在docker环境中
    2. # 设置环境变量`PYTHONPATH`使预览工具可以找到 paddle 的 python 库
    3. export PYTHONPATH=/workplace/Paddle/build/python/
    • 清理旧文件 
    1. # 清除历史生成的文件，如果是第一次使用预览工具可以跳过这一步
    2. rm -rf /workplace/FluidDoc/doc/fluid/menu.json /workplace/FluidDoc/doc/fluid/api/menu.json /tmp/docs/ /tmp/api/
    • 启动预览工具 
    1. cd /workplace/PaddlePaddle.org/portal
    2. pip install -r requirements.txt
    3. ./runserver --paddle /workplace/FluidDoc/

    预览修改

    在要更新的页面上，单击右上角的Refresh Content

    进入使用文档单元后，API部分并不包含内容，希望预览API文档需要点击API目录，几分钟后您将看到生成的 API reference。

    如果您希望修改代码，请在Paddle仓库下参考执行操作。

    如果您仅修改文档：

    • 修改的内容在doc文件夹内，您只需要在FluidDoc仓库下提交PR

    • 修改的内容在文件夹内：

    1.在您修改的仓库下提交PR。这是因为：FluidDoc仓库只是一个包装器，将其他仓库的链接（git术语的“submodule”）集合在了一起。

    2.当您的修改被认可后，更新FluidDoc中对应的submodule到源仓库最新的commit-id。

    • 进入FluidDoc/external/book目录
    • 更新 commit-id 到最新的提交：git pull origin develop
    • 在FluidDoc中提交你的修改

    3.在FluidDoc仓库下为您的修改提交PR

    提交修改与PR的步骤可以参考如何贡献代码

    我们非常欢迎您对平台和支持内容的各个方面做出贡献，以便更好地呈现这些内容。您可以Fork或Clone这个存储库，或者提出问题并提供反馈，以及在issues上提交bug信息。详细内容请参考。