diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000000..a935543b835 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,41 @@ +# Contributing + +Since the open source of PaddlePaddle, we have provided high-quality Chinese and English documents. There are also many developers who have made important contributions to the improvement of the quality of the documentation. Thanks very much for every developer's support for PaddlePaddle documentation. + +## Introduction + +We very much welcome you to participate in the construction of PaddlePaddle documentation and work with us to improve the quality of PaddlePaddle documentation. At present, PaddlePaddle document is divided into the following parts, you can choose any part of your interest to participate: + +- Guides +- Practice +- API Documentation + +### Guides + +This part of the content is mainly a guide to the use of PaddlePaddle. You can correct or improve the existing content, or you can add documents that you think are important. We very much welcome your suggestions and modifications regarding the use of the guides document. + +### Practice + +The Practice is mainly to use PaddlePaddle for specific case implementation. At present, many developers have contributed very good cases, such as OCR recognition, face key-point detection, etc. We welcome you to submit your project to our repo, and finally show it on the official website of PaddlePaddle. + +### API Documentation + +PaddlePaddle's API documentation contains an introduction to the API. We welcome you to propose changes to API documentation, whether it is typo or modification instructions and examples, we are very grateful for any contributions you have made to the API documentation. + +## Participation + +### Guides + +This part of the content is stored in the [docs/docs/guides](https://github.com/PaddlePaddle/docs/tree/develop/docs/guides) directory, you can make your changes by submitting a PR. For more information, please refer to: [Document Contribution Guide](https://github.com/PaddlePaddle/docs/wiki/%E6%96%87%E6%A1%A3%E8%B4%A1%E7%8C%AE%E6%8C%87%E5%8D%97) . + +### Practice + +This part of the content is divided into two parts, the source code and the official website documentation. The source code is stored in the form of a notebook in [book/paddle2.0_docs](https://github.com/PaddlePaddle/book/tree/develop/paddle2.0_docs) directory; after your notebook file is merged, we will convert it into an md file and store it in [docs/docs/tutorial](https: //github.com/PaddlePaddle/docs/tree/develop/docs/tutorial), and then presented to the official website. For more information, please refer to: [[Call for Contribution] Tutorials for PaddlePaddle 2.0](https://github.com/PaddlePaddle/book/issues/905). + +### API Documentation + +PaddlePaddle provides API documentation in both Chinese and English. The English API documentation is stored in the [Paddle](https://github.com/PaddlePaddle/Paddle/tree/develop/python/paddle), you can modify English documents at this location; and Chinese API documents are stored in the [docs/docs/api](https://github.com/PaddlePaddle/docs/tree/develop/docs/api). You can fix and improve any errors and content in the document, or add content that you think is needed in the document. We are very grateful for all your contributions to the API document. For more information, please refer to: [English API Documentation Contribution Guide](https://github.com/PaddlePaddle/docs/wiki/%E8%8B%B1%E6%96%87API%E6%96%87%E6%A1%A3%E8%B4%A1%E7%8C%AE%E6%8C%87%E5%8D%97), [Chinese API Documentation Contribution Guide](https://github.com/PaddlePaddle/docs/wiki/%E4%B8%AD%E6%96%87API%E6%96%87%E6%A1%A3%E8%B4%A1%E7%8C%AE%E6%8C%87%E5%8D%97). + +## Submit PR + +Any modification of PaddlePaddle documentation should be completed by submitting a PR. For more information, please refer to [Submit PR](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/guides/08_contribution/local_dev_guide.html) diff --git a/CONTRIBUTING_cn.md b/CONTRIBUTING_cn.md new file mode 100644 index 00000000000..03d9789c769 --- /dev/null +++ b/CONTRIBUTING_cn.md @@ -0,0 +1,41 @@ +# 贡献文档 + +飞桨框架自开源以来，就提供了高质量的中英文文档。也有许多开发者为文档质量的提升，做出了重要的贡献，非常感谢每一位开发者对飞桨文档的支持。 + +## 文档说明 + +飞桨框架非常欢迎你参与到飞桨文档的建设中，与我们一同提升飞桨文档的质量。目前，飞桨文档分为以下几个部分，你可以选择任意你感兴趣的部分来参与： + +- 使用教程 +- 应用实践 +- API文档 + +### 使用教程 + +这部分内容主要是对飞桨框架的使用指南的说明，你可以对现有的内容进行纠错或者是改进，也可以新增你认为重要的文档在这个栏目中。我们非常欢迎你提出任何关于使用教程文档的建议以及修改。 + +### 应用实践 + +应用实践主要是使用飞桨框架进行具体的案例实现。目前已经有许多开发者贡献了非常优秀的案例，如OCR识别、人脸关键点检测等，我们非常欢迎你提交你的项目到我们的repo中来，并最终呈现在飞桨的官网上。 + +### API文档 + +API文档是飞桨框架的API文档，包含了飞桨框架API的说明介绍。我们非常欢迎你对我们的API文档提出修改，不管是typo或者是修改说明与示例，我们都非常感谢你对于API文档所作出的任何贡献。 + +## 参与方式 + +### 使用教程 + +这部分内容存放在 [docs/docs/guides](https://github.com/PaddlePaddle/docs/tree/develop/docs/guides) 目录下，你可以通过提交PR的方式，来作出你的修改。具体修改方式请参考：[文档贡献指南](https://github.com/PaddlePaddle/docs/wiki/%E6%96%87%E6%A1%A3%E8%B4%A1%E7%8C%AE%E6%8C%87%E5%8D%97)。 + +### 应用实践 + +这部分内容分为源代码与官网文档两部分，源代码的部分以notebook的形式，存放在 [book/paddle2.0_docs](https://github.com/PaddlePaddle/book/tree/develop/paddle2.0_docs) 目录下，你可以提交你的notebook格式的源码于该目录中；在你的notebook文件被合入后，我们会将其转为md文件，存储在[docs/docs/tutorial](https://github.com/PaddlePaddle/docs/tree/develop/docs/tutorial)中，然后呈现到官网。具体信息请参考：[[Call for Contribution] Tutorials for PaddlePaddle 2.0](https://github.com/PaddlePaddle/book/issues/905). + +### API文档 + +飞桨框架同时提供中英文API文档。其中，英文API文档存于[Paddle](https://github.com/PaddlePaddle/Paddle/tree/develop/python/paddle)源代码中，绝大部分通过官网文档的源代码即可链接到，你可以在此位置对英文文档进行修改；而中文API文档存放在[docs/docs/api](https://github.com/PaddlePaddle/docs/tree/develop/docs/api)目录下。你可以针对文档中的任何错误与内容进行修复与完善，或者是新增你认为该文档中所需要的内容，我们非常感谢你对于API文档所付出的一切。具体修改方式请参考：[英文API文档贡献指南](https://github.com/PaddlePaddle/docs/wiki/%E8%8B%B1%E6%96%87API%E6%96%87%E6%A1%A3%E8%B4%A1%E7%8C%AE%E6%8C%87%E5%8D%97)、[中文API文档贡献指南](https://github.com/PaddlePaddle/docs/wiki/%E4%B8%AD%E6%96%87API%E6%96%87%E6%A1%A3%E8%B4%A1%E7%8C%AE%E6%8C%87%E5%8D%97)。 + +## 提交PR + +你对于飞桨文档的任何修改，都应该通过提交PR的方式来完成，具体的方法可以参考[提交PR](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/guides/08_contribution/local_dev_guide.html) diff --git a/README.md b/README.md index b1852379ea9..319dfd5452c 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,43 @@ -

FluidDoc

+# PaddlePaddle docs English | [简体中文](./README_cn.md) -# Introduction -FluidDoc consolidates all the documentations related to Paddle. It supplies the contents to PaddlePaddle.org via CI. +Source files for contents presented at [PaddlePaddle documentation](https://www.paddlepaddle.org.cn/documentation/docs/zh/guides/index_cn.html). -# Architecture -FluidDoc submodules Paddle, Book under `external` folder. All submodules should be put under `external` as standard practice. +Note: English version API docs are generaly docstrings in [PaddlePaddle/Paddle](https://github.com/PaddlePaddle/Paddle), documents for [other PaddlePaddle projects](https://www.paddlepaddle.org.cn/overview) are being managed in their respective ways. -FluidDoc then uses them as references to load up the documents. The FluidDoc constructs the whole doc-tree under the `FluidDoc/doc/fluid` folder. The entry point is `FluidDoc/doc/fluid/index_cn.rst` and `FluidDoc/doc/fluid/index_en.rst` +## Codebase structure -When a release branch is pushed to Github, Travis-CI will start automatically to compile documents and deploy documents to the server. +- [doc](doc): PaddlePaddle 1.8 & older versions docs source file, will be deleted in the future +- [docs](docs): PaddlePaddle 2.0 & above docs source file, +- [docs/api](docs/api): PaddlePaddle API docs +- [docs/guides](docs/guides): PaddlePaddle guides docs +- [docs/tutorial](docs/tutorial): PaddlePaddle tutorial docs +- [ci_scripts](ci_scripts): docs CI scripts -## Note: -FluidDoc needs Paddle python module to compile API documents. Unfortunately, compiling Paddle python module takes longer time Travis CI permits. Usually Travis CI will fail due because of timeout. That's why there three jobs on Travis, two of them are to build libraries. Once the libraries are cached on the Travis, next build will be a lot faster. +## How to build -## Preview with PPO -To preview documents constructured by FluidDoc. Please follow the [regular preview step](https://github.com/PaddlePaddle/PaddlePaddle.org/blob/develop/README.md), but replace the path to paddle with the path to FluidDoc -`./runserver --paddle ` +- pre-requirements + - docker +- Instructions + - step1: clone docs + ``` + git clone https://github.com/PaddlePaddle/docs + ``` + - step2: build docs + ``` + cd docs + mkdir output + bash docs-build.sh -f absolute_path_docs + ``` + - step3: preview docs + The output of docs will be generated in docs/output. -# Publish New release -1. Checkout a new release branch. The branch name should follow `release/` -1. Update the documentations on the submodules or within FluidDoc -1. Make sure all the submodules are ready for release. Paddle, book should all have stable commits. Note: Paddle repo should update the API RST files accordinly if Paddle changes the included module/classes. -1. Update the submodules under `external` folder and commit the changes. -1. Git push the branch to Github, Travis CI will start several builds to publish the documents to the PaddlePaddle.org server -1. Please notify the PaddlePaddle.org team that the release content is ready. PaddlePaddle.org team should enable the version and update the default version to the latest one. PaddlePaddle.org should also update the search index accordingly (Until the search server is up) +## How to contribute + +PaddlePaddle welcomes documentation contributions, please see [CONTRIBUTING.md](./CONTRIBUTING.md) for details. + +## License + +[Apache License 2.0](LICENSE) diff --git a/README_cn.md b/README_cn.md index c59f886b55c..7c4d82b7406 100644 --- a/README_cn.md +++ b/README_cn.md @@ -1,33 +1,42 @@ - -

FluidDoc

+# PaddlePaddle docs [English](./README.md) | 简体中文 -# 介绍 +docs 是 [PaddlePaddle 官网文档](https://www.paddlepaddle.org.cn/documentation/docs/zh/guides/index_cn.html) 的源文件。 -FluidDoc包含了所有PaddlePaddle相关的文档，它通过CI系统为PaddlePaddle.org提供文档内容 +注意：英文版API文档直接从[PaddlePaddle/Paddle](https://github.com/PaddlePaddle/Paddle) 的 docstring 中生成，[飞桨其他项目](https://www.paddlepaddle.org.cn/overview)的文档分别在其对应的位置中管理。 -# 架构 +## 仓库结构 -FluidDoc将Paddle, Book 作为子模块，并放置在 `external` 目录下。按照标准做法，所有的子模块应当置于`external` 目录下 +- [doc](doc): 飞桨框架 1.8 以及更老版本文档的源文件，会在未来删除。 +- [docs](docs): 飞桨框架 2.0 以及之后版本文档的源文件。 +- [docs/api](docs/api): 飞桨中文 API文档的源文件。 +- [docs/guides](docs/guides): 飞桨官方教程的源文件。 +- [docs/tutorial](docs/tutorial): 飞桨相关案例的源文件。 +- [ci_scripts](ci_scripts): docs CI 相关的文件。 -FluidDoc通过引用这些子模块来加载这些Repo中的文档。FluidDoc在 `FluidDoc/doc/fluid` 目录下构建了文档的整体树形结构。可以分别在 `FluidDoc/doc/fluid/index_cn.rst` 和 `FluidDoc/doc/fluid/index_en.rst` 查看。 +## 如何构建文档 -当一个新发布的分支被push到了Github上，Travis-CI 将会自动启动编译文档并把文档部署到服务器 +- 依赖 + - docker +- 构建过程 + - step1: clone docs + ``` + git clone https://github.com/PaddlePaddle/docs + ``` + - step2: build docs + ``` + cd docs + mkdir output + bash docs-build.sh -f absolute_path_docs + ``` + - step3: preview docs + 输出的文件会保存在 docs/output 路径下. -## 注意： -FluidDoc 需要Paddle Repo的python模块去编译生成API文档。但由于Paddle的python模块过于庞大，超过了Travis CI允许的最大时长，通常Travis CI将会因为超时问题失败。这是Travis上有三项作业的原因，其中两项用于构建库。当Travis缓存了这些库以后，下一次的构建将会变得非常的快。 +## 贡献 -## 通过PaddlePaddle.org预览文档 +我们非常欢迎你贡献文档！你可以参考 [贡献指南](CONTRIBUTING_cn.md) 直接参与。 -为了预览FluidDoc的文档，请按照[常规预览步骤](https://github.com/PaddlePaddle/PaddlePaddle.org/blob/develop/README.md)，但请在这一步将 paddle 的路径替换为 Fluid 的路径 -`./runserver --paddle ` +## License -## 发布新的分支 -1. 创建一个新的分支，此分支的名字应遵循`release/` -1. 在FluidDoc和子模块中更新文档 -1. 确认所有的子模块中处于发布就绪的状态。Paddle, book 应全部有稳定的commit -请注意：如果Paddle Repo更改了module/classes，涉及API文档的RST文件应当也被更新 -1. 在 `external` 中更新文件然后commit文档变更 -1. 将这个分支push到Github，Travis CI将会启动几项构建工作以把文档发布到PaddlePaddle.org的服务器 -1. 请告知PaddlePaddle.org团队，发布的内容已经就绪。PaddlePaddle.org团队将使版本生效并更新默认的版本到最新版。PaddlePaddle.org也应当更新相应的搜索引擎文件 +[Apache License 2.0](LICENSE)