文档¶

This introductory guide will help you acquire the tools and knowledge needed to contribute to the documentation.

Read the introduction to the reStructuredText language if you are not familiar with it. Then, there are two courses of action to start contributing to the documentation:

For minor changes, such as adding a paragraph or fixing a typo, we recommend using the GitHub interface. This is the easiest and fastest way to submit changes, and it is suitable for non-technical people. Jump directly to the Contributing to the documentation section to get started.
For more complex changes, such as adding a new page, it is necessary to use Git and work from a local copy of the documentation. Follow the instructions in the 环境设置 section first to prepare your environment.

另请参阅

Discover other ways to contribute to Odoo

重构文本 (RST)¶

The documentation is written in reStructuredText (RST), a lightweight markup language consisting of regular text augmented with markup, which allows including headings, images, notes, and so on. RST is easy to use, even if you are not familiar with it.

重要

Be mindful of our content and RST guidelines as you write documentation. This ensures that the documentation stays consistent and facilitates the approval of changes by the Odoo team.

环境设置¶

下面的说明帮助您准备环境以便在本地对文档进行修改，然后将其推送到 GitHub。如果您已经完成了这一步骤或者想要从 GitHub 界面进行修改，请跳过本节并转到 Contributing to the documentation。

First, create a GitHub account. Odoo uses GitHub to manage the source code of its products, and this is where you will submit your changes.
Generate a new SSH key and register it on your GitHub account.
前往 github.com/odoo/documentation 并点击右上角的 Fork 按钮来创建一个分支 (你自己的副本) 到你的账户。这将创建一个代码库的副本，你可以在其中进行更改而不影响主要代码库。如果你在 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.

请确认 Git 的安装目录已经包含在您系统的 PATH 变量中。

按照在Linux和macOS上更新PATH变量的指南使用Git的安装路径（默认为 /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 将更改推送到您的 fork 而不是主代码库。在下面的命令中，将 <your_github_account> 替换为您创建 fork 的 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

Install the latest release of Python and pip.
使用pip安装文档的Python依赖项。
```
$ pip install -r requirements.txt
```
验证 Python 依赖项的安装目录是否包含在系统的 PATH 变量中。

按照在Linux和macOS上更新PATH变量的指南，使用Python依赖项的安装路径（默认为 ~/.local/bin）进行操作。
安装 Make。
$ sudo apt install make -y
请按照在Windows上安装Make的指南进行操作。
Install pngquant.
You are now ready to make your first contribution with Git.

Contributing to the documentation¶

First, create a GitHub account. Odoo uses GitHub to manage the source code of its products, and this is where you will submit your changes.
请确认您正在浏览您想要更改的文档版本。您可以从顶部菜单中的下拉菜单中选择版本。
前往您想要更改的页面，然后点击页面右上角的在 GitHub 上编辑按钮。
点击 Fork this repository 按钮创建一个分支 (你自己的副本) 到你的账户上。这将创建一个代码库的副本，你可以在其中进行更改而不影响主要的代码库。如果你在 Odoo 工作，则跳过此步骤。
在进行所需更改时，请注意遵循 content 和 RST 指南。

小技巧
点击预览更改按钮以以更易读的格式查看您的贡献。请注意，预览无法正确处理所有标记。例如，注释和提示将显示为纯文本。
滚动到页面底部并填写小表单以提出您的更改。在第一个文本框中，写下您更改的非常简短的摘要。例如，”修复一个拼写错误”或”添加销售订单发票的文档”。在第二个文本框中，解释 为什么 您提出这些更改。然后，点击提出更改按钮。
审核您的更改并单击创建拉取请求按钮。
勾选 Allow edits from maintainer 复选框。如果你在 Odoo 工作，则跳过此步骤。
Review the summary that you wrote about your changes and click on the Create pull request button again.
在页面底部，检查合并状态并解决任何问题。
As soon as your PR is ready for merging, a member of the Odoo team is automatically assigned for review. If the reviewer has questions or remarks, they will post them as comments and you will be notified by email. Those comments must be resolved for the contribution to go forward.
Once your changes are approved, the reviewer merges them and they appear online the next day.

重要

一些步骤需要熟悉 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.
Create a new branch starting from branch 18.0. Prefix the branch name with the base branch: 18.0-.... If you work at Odoo, suffix the branch name with your Odoo handle: 18.0-...-xyz.
Example
```
$ git switch -c 18.0-explain-pricelists
```
```
$ git switch -c 18.0-explain-pricelists-xyz
```
在进行所需更改时，请注意遵循 content 和 RST 指南。

Compress all PNG images that were added or modified.

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

Write a redirect rule for every RST file that were renamed.
Build the documentation with make. Then, open _build/index.html in a web browser to browse the documentation with your changes.

小技巧
使用 make help 命令来了解其他有用的命令。
提交您的更改。按照 Git指南中的说明编写清晰的提交消息。
```
$ git add .
$ git commit
```
Push your changes to your fork, for which we added the remote alias 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. Select 18.0 for the base.
3. 点击 compare across forks.
4. 选择 <your_github_account>/odoo 作为主仓库。将 <your_github_account> 替换为您在 GitHub 上创建分支的账户名。如果您在 Odoo 工作，则跳过此步骤。
5. 审核您的更改并单击创建拉取请求按钮。
6. 勾选 Allow edits from maintainer 复选框。如果你在 Odoo 工作，则跳过此步骤。
7. 完成描述并再次点击创建拉取请求按钮。
在页面底部，检查合并状态并解决任何问题。
As soon as your PR is ready for merging, a member of the Odoo team is automatically assigned for review. If the reviewer has questions or remarks, they will post them as comments and you will be notified by email. Those comments must be resolved for the contribution to go forward.
Once your changes are approved, the reviewer merges them and they appear online the next day.

Edit on GitHub