文档¶

这个入门指南将帮助您获得贡献文档所需的工具和知识。

阅读 reStructuredText 语言简介，如果您不熟悉它的话。然后，有两条行动路径可以开始为文档做出贡献：

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

另请参见

了解其他为 Odoo 做贡献的方式

重结构化文本（RST）¶

文档使用 reStructuredText (RST) 编写，这是一种轻量级标记语言，由常规文本加上标记组成，可以包含标题、图片、注释等。RST 使用起来非常简单，即使您不熟悉它也没关系。

重要

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

环境设置¶

以下说明将帮助您准备环境，以便对文档进行本地修改，然后将其推送到 GitHub。如果您已经完成此步骤或希望从 GitHub 界面进行修改，请跳过本节，直接前往贡献文档。

首先，创建一个 GitHub 账户。Odoo 使用 GitHub 来管理其产品的源代码，这也是您提交更改的地方。
Generate a new SSH key and register it on your GitHub account.
前往 github.com/odoo/documentation，并点击右上角的分叉按钮，以在您的账户中创建该仓库的分叉 (您自己的副本)。这将创建一个代码库的副本，您可以对其进行修改而不会影响主代码库。如果您在 Odoo 工作，请跳过此步骤。
Install Git. It is a command-line (a text interface) tool that allows tracking the history of changes made to a file and, more importantly, working on different versions of that file simultaneously. It means you do not need to worry about overwriting someone else’s pending work when making changes.

Verify that the installation directory of Git is included in your system’s PATH variable.

Follow the guide to update the PATH variable on Linux and macOS with the installation path of Git (by default /usr/bin/git).
配置 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
按照在 Windows 上安装 Make 的指南进行操作。
安装 pngquant
你现在已准备好通过 Git 进行首次贡献。

贡献文档¶

首先，创建一个 GitHub 账户。Odoo 使用 GitHub 来管理其产品的源代码，这也是您提交更改的地方。
确认您正在浏览的文档版本是您打算修改的版本。可以通过顶部菜单中的下拉菜单选择版本。
前往您要修改的页面，然后点击页面右上角的在 GitHub 上编辑按钮。
点击 Fork 此仓库按钮，以在您的账户上创建一个副本 (您自己的副本)。这将创建一个代码库的副本，您可以对其进行修改而不会影响主代码库。如果您在 Odoo 工作，请跳过此步骤。
在进行所需更改时，请注意遵循内容和 RST 指南。

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

重要

此指南中的一些步骤需要您对 Git 有一定的了解。如果您在某个步骤遇到困难，这里有一些教程和一个交互式培训。

既然你的环境已经配置完成，就可以开始为文档做出贡献了。在终端中，导航到你克隆源代码的目录，并按照下面的指南操作。

请选择您希望进行修改的文档版本。请注意，针对不支持的 Odoo 版本的贡献是不被接受的。本指南假设您修改的是 Odoo 18 的文档，对应分支为 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> 替换为你创建 fork 的 GitHub 账户名称。如果你在 Odoo 工作，请跳过此步骤。
5. 查看您的更改，然后点击创建拉取请求按钮。
6. 勾选允许维护者进行编辑复选框。如果您在 Odoo 工作，请跳过此步骤。
7. 请完成描述，然后再次点击创建拉取请求按钮。
页面底部，检查可合并状态并解决任何问题。
一旦您的 PR 准备好可以合并，Odoo 团队的一名成员将被自动分配进行审查。如果审查人员有疑问或意见，他们将以评论的形式提出，您将通过电子邮件收到通知。这些评论必须得到解决，贡献才能继续推进。
一旦您的更改获得批准，审核人将将其合并，并于次日在线显示。

Edit on GitHub