本文介紹 win10 + ubuntu on win 下如何使用Sphinx。
1. 寫在前面
文中使用的Sphinx的版本信息如下：
➜ Pictures sphinx-build --version
sphinx-build 3.2.1
2. 安裝Sphinx和Pandoc
2.1 安裝 Sphinx
-
安裝 python3
-
安裝 pip3
-
打開windows終端
win+r -
安裝 Sphinx
pip install -U sphinx -
將sphinx的路徑添加到系統PATH中
-
驗證是否安裝成功
sphinx-build --version
2.2 安裝 Pandoc
3. 個人文檔
本節中用到的代碼示例存放在這里: sphinx-doc-guide
3.1 創建目錄並進入
mkdir sphinx-doc-guide && cd sphinx-doc-guide
3.2 初始化文檔
➜ sphinx-doc-guide sphinx-quickstart
歡迎使用 Sphinx 3.2.1 快速配置工具。
Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).
Selected root path: .
You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> 獨立的源文件和構建目錄（y/n） [n]: y
The project name will occur in several places in the built documentation.
> 項目名稱: sphinx-doc-guide
> 作者名稱: double12gzh
> 項目發行版本 []: v1.0
If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.
For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> 項目語種 [en]: zh
創建文件 /mnt/c/Users/jeffrey/Pictures/sphinx-doc-guide/source/conf.py。
創建文件 /mnt/c/Users/jeffrey/Pictures/sphinx-doc-guide/source/index.rst。
創建文件 /mnt/c/Users/jeffrey/Pictures/sphinx-doc-guide/Makefile。
創建文件 /mnt/c/Users/jeffrey/Pictures/sphinx-doc-guide/make.bat。
完成：已創建初始目錄結構。
You should now populate your master file /mnt/c/Users/jeffrey/Pictures/sphinx-doc-guide/source/index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.
3.3 查看文檔結構
➜ sphinx-doc-guide tree
.
├── build
├── make.bat
├── Makefile
└── source
├── conf.py
├── index.rst
├── _static
└── _templates
4 directories, 4 files
說明：
buid這個目錄是每次執行make html自動生成的，可以刪除- 添加.gitignore，忽略build
3.4 定制conf.py
根據自己項目提供的信息將sphinx-doc-guide進行替換。
➜ source grep -rin "sphinx-doc-guide" ./
./conf.py:54:project = u'sphinx-doc-guide'
./conf.py:232: (master_doc, 'sphinx-doc-guide.tex', u'sphinx-doc-guide.Documentation',
./conf.py:262: (master_doc, 'sphinx-doc-guide', u'sphinx-doc-guide中文文檔',
./conf.py:276: (master_doc, 'sphinx-doc-guide', u'sphinx-doc-guide文檔',
./conf.py:277: author, 'sphinx-doc-guide', 'One line description of project.',
./conf.py:295: app.add_config_value('sphinx-doc-guide_config', {
根據項目情況修改以下信息：
➜ source grep -rin "double12gzh" ./
./conf.py:55:copyright = u'2020, double12gzh'
./conf.py:56:author = u'double12gzh'
./conf.py:233: u'double12gzh', 'manual'),
3.5 修改favicon.ico
ico文件的路徑為：
sphinx-doc-guide/source/_static/img/favicon.ico
3.6 根據需要寫組織文檔
可以參考本例進行組織
3.7 生成線下預覽
➜ sphinx-doc-guide make html
正在運行 Sphinx v3.2.1
正在加載翻譯 [zh]... 完成
創建輸出目錄... 完成
構建 [mo]： 0 個 po 文件的目標文件已過期
構建 [html]： 15 個源文件的目標文件已過期
更新環境: [新配置] 已添加 15，0 已更改，0 已移除
閱讀源... [ 6%] 0-root /root/anaconda3/lib/python3.7/site-packages/recommonmark/parser.py:75: UserWarning: Container node skipped: type=document
warn("Container node skipped: type={0}".format(mdnode.t))
閱讀源... [ 13%] index 閱讀源... [ 20%] makefile/0-mk 閱讀源... [ 26%] makefile/1/0-introduction 閱讀源... [ 33%] makefile/1/index 閱讀源... [ 40%] makefile/2/1-mk 閱讀源... [ 46%] makefile/2/2-mk 閱讀源... [ 53%] makefile/2/index 閱讀源... [ 60%] makefile/3-pic 閱讀源... [ 66%] makefile/index 閱讀源... [ 73%] python/0-py 閱讀源... [ 80%] python/1-py 閱讀源... [ 86%] python/11 閱讀源... [ 93%] python/2 閱讀源... [100%] python/index
查找當前已過期的文件... 沒有找到
pickling環境... 完成
檢查一致性... 完成
准備文件... 完成
寫入輸出... [ 6%] 0-root 寫入輸出... [ 13%] index 寫入輸出... [ 20%] makefile/0-mk 寫入輸出... [ 26%] makefile/1/0-introduction 寫入輸出... [ 33%] makefile/1/index 寫入輸出... [ 40%] makefile/2/1-mk 寫入輸出... [ 46%] makefile/2/2-mk 寫入輸出... [ 53%] makefile/2/index 寫入輸出... [ 60%] makefile/3-pic 寫入輸出... [ 66%] makefile/index 寫入輸出... [ 73%] python/0-py 寫入輸出... [ 80%] python/1-py 寫入輸出... [ 86%] python/11 寫入輸出... [ 93%] python/2 寫入輸出... [100%] python/index
generating indices... genindex完成
writing additional pages... search完成
復制靜態文件... ... 完成
copying extra files... 完成
dumping search index in Chinese (code: zh)... 完成
dumping object inventory... 完成
構建 成功.
HTML 頁面保存在 build/html 目錄。
生成的文件位於項目根目錄的build中。
如果需要清除生成的文件可使用make clean
4. 個人博客
請參考gzh
5. github與readthedocs聯動
5.1 注冊readthedocs帳號
5.2 導入項目
6. 總結
-
文章中完成的文檔托管的頁面為sphinx-doc-guide
-
博客頁面為gzh