文档¶

本入门指南将帮助您获取编写文档所需的工具和知识，无论您计划进行小的内容更改还是从头开始记录应用程序。

另请参阅

Discover other ways to contribute to Odoo

阅读 reStructuredText 语言介绍，如果您对此不熟悉。然后，您有两种行动方案来开始为文档做出贡献，具体取决于您是想对现有内容提出较小的更改，还是想对新的和现有内容进行重大更改。

对于小的更改，例如添加一个段落或修复一个拼写错误，我们建议**使用GitHub界面**。这是提交更改的最简单和最快的方式，适合非技术人员使用。直接跳转到:ref:`contributing/documentation/first-contribution`部分开始。
对于更复杂的更改，需要**使用 Git** 并从本地副本的文档中进行工作。请按照环境设置部分的说明，首先准备好您的环境。

重构文本 (RST)¶

文档是用 reStructuredText (RST) 编写的，这是一种 轻量级标记语言 <https://en.wikipedia.org/wiki/Lightweight_markup_language> _，由常规文本与标记增强而成，可以包含标题、图片、注释等。这可能看起来有点抽象，但不用担心； RST 并不难学，尤其是如果你打算对内容进行小的更改。

如果您需要了解特定的标记，请转到我们的 RST 速查表；它包含了您在 Odoo 文档中所需的所有信息。

重要

我们恳请您在撰写文档时遵守一套内容和 RST 指南。这样可以确保您与其他文档保持一致，并且方便Odoo团队审核您的内容更改。

另请参阅

环境设置¶

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

首先，你需要创建一个 GitHub 账号。Odoo 使用 GitHub 来管理其产品的源代码，这也是你将进行更改并提交审核的地方。
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

安装最新版本的 Python 和 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.
就是这样！你已经准备好使用Git :ref:`进行你的第一次贡献 <contributing/documentation/first-contribution>`了。

进行你的第一次贡献¶

请确认您正在浏览您想要更改的文档版本。您可以从顶部菜单中的下拉菜单中选择版本。
前往您想要更改的页面，然后点击页面右上角的在 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.
在页面底部，检查合并状态并解决任何问题。
一旦您的 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 16, which corresponds to branch 16.0.
从分支16.0开始创建一个新分支。将分支名称前缀设为基础分支： 16.0-... 。如果您在Odoo工作，请在分支名称后缀中加上您的Odoo句柄： 16.0-...-xyz 。
Example
```
$ git switch -c 16.0-explain-pricelists
```
```
$ git switch -c 16.0-explain-pricelists-xyz
```
在进行所需更改时，请注意遵循 content 和 RST 指南。

压缩您添加或修改的所有PNG图像。

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

为每个重命名的RST文件编写一个 重定向规则 <https://github.com/odoo/documentation/tree/16.0/redirects/MANUAL.md> _。
使用 make 命令构建文档。然后，在您的网页浏览器中打开 _build/index.html 文件以浏览带有您的更改的文档。

小技巧
使用 make help 命令来了解其他有用的命令。
提交您的更改。按照 Git指南中的说明编写清晰的提交消息。
```
$ git add .
$ git commit
```
将您的更改推送到您的分支，我们为其添加了远程别名 dev。
Example
```
$ git push -u dev 16.0-explain-pricelists
```
如果你在Odoo工作，请直接将你的更改推送到主代码库，其远程别名为 origin。
Example
```
$ git push -u origin 16.0-explain-pricelists-xyz
```
在 GitHub 上打开一个 PR 来提交你的更改以供审查。
1. 前往 odoo/documentation 代码库的比较页面.
2. 选择 16.0 作为基础版本。
3. 点击 compare across forks.
4. 选择 <your_github_account>/odoo 作为主仓库。将 <your_github_account> 替换为您在 GitHub 上创建分支的账户名。如果您在 Odoo 工作，则跳过此步骤。
5. 审核您的更改并单击创建拉取请求按钮。
6. 勾选 Allow edits from maintainer 复选框。如果你在 Odoo 工作，则跳过此步骤。
7. 完成描述并再次点击创建拉取请求按钮。
在页面底部，检查合并状态并解决任何问题。
一旦您的 PR 准备好合并，Odoo 团队的成员将自动被分配进行审查。如果审查人员有问题或备注，他们将以评论的形式发布，并通过电子邮件通知您。这些评论必须解决，以便推进贡献。
一旦您的更改被批准，审核人员会将其合并，然后它们会在第二天出现在网上！

Edit on GitHub