Readthedocs+Github搭建文檔

標籤：現在   webhook   添加   min   鉤子   oct   window   net   build   

環境配置

要求已經具備下列工具：

• Python
• pip

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

原文連結：Getting Started

1. 安裝Sphinx美化文章

$ pip install sphinx sphinx-autobuild

1. 在本地建立一個你要儲存文檔的檔案夾，然後進入到該檔案夾

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

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

$ sphinx-quickstart

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

$ make html

1. 開啟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_themehtml_theme = "sphinx_rtd_theme"html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

理解書寫格式和檔案組織方式

• 理解rst檔案

• 理解toctree指令

Readthedocs+Github搭建文檔