文檔?

本入門指南將幫助您獲取編寫文檔所需的工具和知識，無論您計劃進行小的內容更改還是從頭開始記錄應用程序。

另請參閱

發現其他貢獻Odoo的方式

如果您不熟悉reStructuredText語言，請閱讀 reStructuredText語言介紹。然后，您可以選擇兩種行動方案開始為文檔做出貢獻，具體取決于您是想對現有內容提出小的更改，還是想對新的和現有內容進行重大更改。

對于小的更改 ，例如添加一個段落或修復一個錯別字，我們建議 使用GitHub界面 。這是提交更改最簡單和最快的方法，適合非技術人員。直接跳轉到進行你的第一次貢獻部分開始。
對于更復雜的更改 ，需要 使用Git 并從本地文檔副本中進行工作。請按照環境設置部分中的說明，首先準備好您的環境。

重構文本 (RST)?

文檔使用 reStructuredText (RST) 編寫，這是一種輕量級標記語言，由普通文本和標記組成，可以包含標題、圖片、注釋等。這可能看起來有點抽象，但不用擔心； RST 并不難學，特別是如果您只是打算對內容進行小的修改。

如果您需要了解特定標記，請前往我們的 RST速查表；它包含了您在Odoo文檔編寫中所需的所有信息。

重要

我們懇請您在編寫文檔時遵守一系列內容指南和 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 將更改推送到您的 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 ）添加到PATH變量中。
安裝 Make。
$ sudo apt install make -y
按照在Windows上安裝Make的指南進行操作。
安裝 pngquant.
就是這樣！你已經準備好使用Git 進行第一次貢獻了。

進行你的第一次貢獻?

請確認您正在瀏覽您想要更改的文檔版本。您可以從頂部菜單中的下拉菜單中選擇版本。
前往您想要更改的頁面，點擊頁面右上角的 Edit on GitHub 按鈕。
點擊 Fork this repository 按鈕，在您的賬戶上創建一個分支 ( 您自己的副本 )。這將創建一個代碼庫的副本，您可以在其中進行更改，而不會影響主代碼庫。如果您在Odoo工作，則可以跳過此步驟。
在進行所需更改時，請注意遵循內容指南和 RST指南。

小技巧
點擊預覽更改按鈕，以更人性化的格式查看您的貢獻。請注意，預覽無法正確處理所有標記。例如，注釋和提示將顯示為純文本。
滾動到頁面底部，填寫小表格以提出您的更改建議。在第一個文本框中，寫下您更改的非常簡短的摘要。例如，“修復一個錯別字”或“添加銷售訂單發票的文檔”。在第二個文本框中，解釋 為什么 您提出這些更改建議。然后，點擊 Propose changes 按鈕。
請檢查您的更改，然后單擊創建拉取請求按鈕。
勾選允許維護者編輯復選框。如果您在Odoo工作，則跳過此步驟。
請檢查您對更改所寫的摘要，并再次單擊“ 創建拉取請求 ”按鈕。
在頁面底部，檢查合并狀態并解決任何問題。
一旦您的 PR 準備好合并，Odoo 團隊的成員將自動分配進行審核。如果審核人員有問題或者意見，他們會在評論中發表，您將通過電子郵件收到通知。這些評論必須解決，以便貢獻能夠繼續前進。
一旦您的更改被批準，審核人員會將其合并，然后它們會在第二天出現在網上！

重要

本指南的某些步驟需要您熟悉 Git。如果您在某些地方卡住了，這里有一些教程和一個交互式培訓。

現在您的環境已經設置好，您可以開始為文檔做出貢獻。在終端中，導航到您克隆源代碼的目錄，并按照下面的指南操作。

選擇您要更改的文檔版本。請注意，不接受針對 Odoo 的不支持版本的貢獻。本指南假定更改針對 Odoo 16 的文檔，對應分支為 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
```
在進行所需更改時，請注意遵循內容指南和 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 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. 點擊比較分支。
4. 選擇 <your_github_account>/odoo 作為主倉庫。將 <your_github_account> 替換為您在 GitHub 上創建分支的賬戶名。如果您在 Odoo 工作，則跳過此步驟。
5. 請檢查您的更改，然后單擊創建拉取請求按鈕。
6. 勾選允許維護者編輯復選框。如果您在Odoo工作，則跳過此步驟。
7. 完善描述后再次點擊創建拉取請求按鈕。
在頁面底部，檢查合并狀態并解決任何問題。
一旦您的 PR 準備好合并，Odoo 團隊的成員將自動分配進行審核。如果審核人員有問題或者意見，他們會在評論中發表，您將通過電子郵件收到通知。這些評論必須解決，以便貢獻能夠繼續前進。
一旦您的更改被批準，審核人員會將其合并，然后它們會在第二天出現在網上！

Edit on GitHub