環境配置

要求已經具備下列工具：

• Python
• pip

本教程是在Windows10上進行搭建的，Linux需要稍作修改

原文鏈接：Getting Started

1. 安裝Sphinx美化文章

$ pip install sphinx sphinx-autobuild

2. 在本地創建一個你要保存文檔的文件夾，然後進入到該文件夾

$ cd /path/to/project
$ mkdir docs
$ cd docs

3. 使用sphinx-quickstart進行快速配置

$ sphinx-quickstart
 

4. 使用tree查看目錄結構（該步驟可以跳過）
5. 修改 index.rst ，然後運行下面的命令進行預覽

$ make html

6. 打開build文件夾下的html文件，即可預覽。

支持Markdown格式

參考：In Markdown

將本地修改提交到遠程倉庫

首先在根目錄下（也就是和build，source等文件夾在同一級目錄）建立一個.gitignore文件，其內容如下：

build/
.idea/
*.pyc

然後在本地建立一個倉庫，並提交到遠程，步驟如下：

• 第一步：本地建立git倉庫

  cd到你的本地項目根目錄下，執行git命令 git init

• 第二步：將項目的所有文件添加到倉庫中

  git add . 如果想添加某個特定的文件，只需把.換成特定的文件名即可

• 第三步：將add的文件commit到倉庫

  git commit -m "註釋語句"

• 第四步：去github上創建Repository，點擊下面的New Organization，拿到創建的倉庫的https地址，不會創建可以參考GitHub 實現多人協同提交代碼並且權限分組管理

• 第五步：重點來了，將本地的倉庫關聯到github上

  git remote add origin github倉庫地址

• 第六步：上傳github之前，要先pull一下，執行如下命令：

  git pull origin master

  錯誤提示 : fatal: refusing to merge unrelated histories

  解決：在進行git pull 時，添加一個可選項（在更高版本的保護機制） git pull origin master --allow-unrelated-histories

• 第七步，也就是最後一步，上傳代碼到github遠程倉庫

  git push -u origin master

  執行完後，如果沒有異常，等待執行完就上傳成功了，中間可能會讓你輸入Username和Password，你只要輸入github的賬號和密碼就行了

連接Readthedocs和Github

現在，文件已經提交到了你的github倉庫，接下來需要把github和Readthedocs連接起來，連接過程分兩種情況：

1. 個人倉庫。很簡單，在你登錄readthedocs時，直接選擇sign in with github就可以了。
2. 多人合作的倉庫。需要Webhooks（鉤子）才能實現同步，下面著重提一下Webhooks。

首先用github或者用郵箱註冊一個Readthedocs賬號，然後登錄。

然後選擇import a project>>手動導入>>填寫代碼倉庫地址等>>下一頁。

然後就是它自動進行同步了，這是，因為沒有webhooks，所以同步不會成功。

接下來，找到project settings>>Integrations>>GitHub incoming webhook你會進入到下圖的頁面：

將紅色框住的地址復制，粘貼到github的Webhooks中。操作過程是：打開代碼倉庫>>Settings>>Webhooks>>Add webhooks>>Payload URL，如下圖：

接下來你就可以向這個倉庫添加代碼，然後Readthedocs就會有相應的更新。

這樣，一個多人協同辦公的技術文檔就可以搭建起來了。

更改主題 sphinx_rtd_theme

更改source/conf.py:

import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

關於書寫格式和文件組織方式

• 關於rst文件
• 關於toctree指令

Readthedocs+Github搭建文檔