文档¶

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

如果您不熟悉 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。如果您在某个地方遇到困难，可以参考一些教程和交互式培训。

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

Choose the version of the documentation to which you want to make changes. Keep in mind that contributions targeting an unsupported version of Odoo are not accepted. This guide assumes that the changes target the documentation of Odoo 18, which corresponds to branch 18.0.
从分支 18.0 创建一个新分支。分支名称前缀为基分支：18.0-... 。如果您在 Odoo 工作，请在分支名称后缀上添加您的 Odoo 用户名：18.0-...-xyz 。
Example
```
$ git switch -c 18.0-explain-pricelists
```
```
$ git switch -c 18.0-explain-pricelists-xyz
```
在遵循内容和 RST 指南的前提下，进行所需的更改。

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

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

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

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

Edit on GitHub