手把手教你給項目添加文檔
- 2020 年 3 月 27 日
- 筆記
該文檔主要是由Read the Docs這個在線文檔託管、Sphinx這個基於Python的文檔生成項目以及我們常逛的人類精華寶庫GitHub實現的，下面我們就來梳理一下如何生成文檔。
創建倉庫
首先，我們需要在GitHub上創建倉庫並將該倉庫克隆到本地，當然你也可以直接在原有倉庫上進行操作。
註冊帳號並連接到GitHub
接著我們需要在ReadtheDocs官網註冊一個帳號，https://readthedocs.org/ ，註冊成功後在設置中選擇已連接的服務，並點擊Connect to GitHub按鈕。
項目導入
在個人面板點擊Import a Project，選擇需要創建文檔的項目，若是未找到目標項目，可以點擊右上角的刷新並等待。
構建文檔
導入項目之後，我們點擊Build version即可成功創建文檔
等待片刻後即可構建完成，Webhook自動添加之後只要更新GitHub倉庫，項目文檔就會自動重新構建。
然後我們就能夠看到文檔的雛形
添加文檔
在做完上述前期工作之後，我們要來動手書寫自己的文檔。首先，我們需要安裝Sphinx(速度較慢，建議切換成清華鏡像下載)，
pip install sphinx sphinx-autobuild sphinx_rtd_theme pip install sphinx sphinx-autobuild sphinx_rtd_theme -i https://pypi.tuna.tsinghua.edu.cn/simple
接著我們進入到本地倉庫目錄，進行初始化，
sphinx-quickstart
可以通過一直回車來使用默認配置，在這裡我主要選擇了source和build目錄分離，並且使用中文為項目語言。
Separate source and build directories (y/n) [n]:y Project language [en]: zh_CN
然後我們可以通過修改source/conf.py文件來更改文檔主題並添加markdown文件的支援(需要安裝recommonmark)。
import sphinx_rtd_theme html_theme = "sphinx_rtd_theme" html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] from recommonmark.parser import CommonMarkParser source_parsers = { '.md': CommonMarkParser, } source_suffix = ['.rst', '.md']
我們可以通過在項目根目錄執行下述命令在本地生成html文件
make html
並且在build/html/index.html中來預覽項目文檔
最後，我們只需要修改index.rst文件便可以修改文檔內容，reStructuredText 是擴展名為.rst的純文本文件，含義為"重新構建的文本"，其是輕量級標記語言的一種，被設計為容易閱讀和編寫的純文本，具體如何書寫可以參考下面給出的鏈接。
參考資料
- Quick reStructuredText：https://docutils.sourceforge.io/docs/user/rst/quickref.html
- Sphinx： https://docs.readthedocs.io/en/latest/intro/getting-started-with-sphinx.html
