文档¶

本入门指南将帮助您获取为文档做出贡献所需的工具和知识。

如果您不熟悉 reStructuredText 语言，请阅读 reStructuredText 语言简介。然后，有两种方法可以开始为文档做出贡献：

对于小的更改 ，例如添加段落或修复拼写错误，我们建议 使用 GitHub 界面 。这是提交更改最简单、最快捷的方式，适合非技术人员使用。直接跳转到为文档做出贡献部分开始操作。
对于更复杂的更改 ，例如添加新页面，则需要 使用 Git 并从文档的本地副本中进行操作。首先按照环境设置部分中的说明准备您的环境。

另请参阅

探索其他为 Odoo 贡献的方式

reStructuredText (RST)¶

文档使用 reStructuredText (RST) 编写，这是一种轻量级标记语言，由普通文本加上标记组成，允许包含标题、图像、注释等内容。即使您不熟悉它， RST 也非常易于使用。

重要

在撰写文档时，请注意我们的内容指南和 RST 指南。这确保了文档的一致性，并有助于 Odoo 团队批准更改。

环境设置¶

以下说明将帮助您准备环境，以便对文档进行本地更改并将其推送到 GitHub。如果您已完成此步骤或想通过 GitHub 界面进行更改，请跳过本节并转到为文档做出贡献。

首先，创建一个 GitHub 账户。Odoo 使用 GitHub 管理其产品的源代码，这也是您提交更改的地方。
生成一个新的 SSH 密钥并将其注册到您的 GitHub 帐户。
前往 github.com/odoo/documentation 并单击右上角的 Fork 按钮，在您的账户中创建存储库的分支（即您自己的副本）。这会创建代码库的一个副本，您可以在其中进行更改而不会影响主代码库。如果您在 Odoo 工作，请跳过此步骤。
安装 Git 。它是一个命令行工具（文本界面），可以跟踪文件更改的历史记录，并且更重要的是，可以同时处理该文件的不同版本。这意味着在进行更改时，您无需担心会覆盖其他人的未完成工作。

确保 Git 的安装目录已包含在系统的 PATH 变量中。

请按照在 Linux 和 macOS 上更新 PATH 变量的指南，将 Git 的安装路径（默认为 /usr/bin/git ）添加到 PATH 变量中。
配置 Git 以将您标识为未来贡献的作者。输入您在 GitHub 注册时使用的电子邮件地址。
```
$ git config --global user.name "Your Name"
$ git config --global user.email "youremail@example.com"
```

使用 Git 克隆源代码并导航到本地存储库。

$ git clone git@github.com:odoo/documentation.git
$ cd documentation

配置 Git 将更改推送到您的分支而不是主代码库。在以下命令中，将 <your_github_account> 替换为您创建分支时使用的 GitHub 账户名称。如果您在 Odoo 工作，请跳过此步骤。
```
$ git remote add dev git@github.com:<your_github_account>/documentation.git
```

配置 Git 以方便来自不同系统的作者之间的协作。

$ git config --global core.autocrlf input
$ git config commit.template `pwd`/commit_template.txt

$ git config --global core.autocrlf true
$ git config commit.template %CD%\commit_template.txt

安装最新版本的 Python 和 pip 。
使用 pip 安装文档的 Python 依赖项。
```
$ pip install -r requirements.txt
```
验证 Python 依赖项的安装目录是否已包含在系统的 PATH 变量中。

请按照在 Linux 和 macOS 上更新 PATH 变量的指南，将 Python 依赖项的安装路径（默认为 ~/.local/bin ）添加到 PATH 中。
安装 Make。
$ sudo apt install make -y
请按照在 macOS 上安装 Make 的指南进行操作。

请按照在 Windows 上安装 Make 的指南进行操作。
安装 pngquant 。
现在，您可以使用 Git 进行第一次贡献了。

为文档做出贡献¶

首先，创建一个 GitHub 账户。Odoo 使用 GitHub 管理其产品的源代码，这也是您提交更改的地方。
确认您正在浏览的文档是您打算更改的版本。可以通过顶部菜单的下拉列表选择版本。
前往您想更改的页面，并点击页面右上角的在 GitHub 上编辑按钮。
点击派生此仓库按钮，在您的账户上创建仓库的一个分支（即您自己的副本）。这会创建一个代码库的副本，您可以在不影响主代码库的情况下进行更改。如果您在 Odoo 工作，请跳过此步骤。
在遵循内容和 RST 指南的前提下，进行所需的更改。

小技巧
点击预览更改按钮以更易读的格式查看您的贡献。请注意，预览无法正确处理所有标记。例如，注释和提示将以纯文本形式显示。
滚动到页面底部并填写小表单以提交您的更改。在第一个文本框中，简要总结您的更改。例如，“修复拼写错误”或“为销售订单的开票添加文档”。在第二个文本框中，解释您提出这些更改的原因。然后点击提交更改按钮。
检查您的更改并点击创建拉取请求按钮。
勾选允许维护者编辑复选框。如果您在 Odoo 工作，请跳过此步骤。
复查您对更改撰写的摘要，然后再次点击创建拉取请求按钮。
在页面底部，检查可合并状态并解决任何问题。
一旦您的 PR 准备好合并，Odoo 团队的一名成员会自动分配进行审核。如果审核人员有任何问题或意见，他们会以评论的形式发布，您将通过电子邮件收到通知。这些评论必须解决，以便贡献能够继续推进。
一旦您的更改被批准，审核者将合并它们，它们会在次日在线显示。

重要

本指南的某些步骤要求您熟悉 Git。如果您在某个地方遇到困难，可以参考一些教程和交互式培训。

现在您的环境已设置好，您可以开始为文档做出贡献了。在终端中，导航到您克隆源码的目录，并按照以下指南操作。

选择您要修改的文档版本。请注意：针对不受支持的 Odoo 版本的贡献将不被接受。本指南假设修改针对的是 Odoo 20 的文档，对应分支 20.0。
从分支 20.0 创建一个新分支。将分支名以基础分支作为前缀：20.0-...。如果您在 Odoo 工作，请为您的分支名加上 Odoo 句柄作为后缀：20.0-...-xyz。
Example
```
$ git switch -c 20.0-explain-pricelists
```
```
$ git switch -c 20.0-explain-pricelists-xyz
```
在遵循内容和 RST 指南的前提下，进行所需的更改。

压缩所有新增或修改的 PNG 图像。

$ pngquant path/to/image.png
$ mv path/to/image-fs8.png path/to/image.png

为每个已重命名的 RST 文件编写一条 redirect rule。
使用 make 构建文档。然后在浏览器中打开 _build/index.html 以查看包含您更改的文档。

小技巧
使用 make help 查看其他有用的命令。
提交您的更改。按照 Git 指南的说明编写清晰的提交信息。
```
$ git add .
$ git commit
```
将您的更改推送到您的分支，我们为其添加了远程别名 dev 。
Example
```
$ git push -u dev 20.0-explain-pricelists
```
如果您在 Odoo 工作，请直接将更改推送到主代码库，其远程别名为 origin 。
Example
```
$ git push -u origin 20.0-explain-pricelists-xyz
```
在 GitHub 上打开一个 PR ，以提交您的更改供审核。
1. 前往 odoo/documentation 代码库的比较页面。
2. 为基础分支选择 20.0 。
3. 点击跨分支比较。
4. 选择 <your_github_account>/odoo 作为头部仓库。将 <your_github_account> 替换为您创建分支的 GitHub 帐户名称。如果您在 Odoo 工作，请跳过此步骤。
5. 检查您的更改并点击创建拉取请求按钮。
6. 勾选允许维护者编辑复选框。如果您在 Odoo 工作，请跳过此步骤。
7. 完成描述并再次点击创建拉取请求按钮。
在页面底部，检查可合并状态并解决任何问题。
一旦您的 PR 准备好合并，Odoo 团队的一名成员会自动分配进行审核。如果审核人员有任何问题或意见，他们会以评论的形式发布，您将通过电子邮件收到通知。这些评论必须解决，以便贡献能够继续推进。
一旦您的更改被批准，审核者将合并它们，它们会在次日在线显示。

在 GitHub 上编辑