1.效果預覽
https://how-to-use-sphinx-write.readthedocs.io/zh_CN/latest/
2.安裝
2.1准備
安裝之前假設你已經安裝好了python3
- sphinx版本:3.4
- 以下以Linux命令為主,window可以手動創建目錄,然后在cmd執行pip和初始化即可.
#安裝sphinx/主題/markdown
pip install sphinx recommonmark sphinx_rtd_theme
#創建一個目錄docs
mkdir docs
#切換至docs目錄
cd docs
#初始化一個sphinx
sphinx-quickstart
在執行命令sphinx-quickstart的時候，會讓你輸入配置，除了以下幾個個性化配置外，其他的都可以按照默認的來（回車默認配置）。
> Separate source and build directories (y/n) [n]:n
> Project name: how-to-use-sphinx
> Author name(s): jonnyan404
> Project release []: 0.1
> Project language [en]: zh_CN
執行完畢后，就可以看見創建的工程文件
- _build：文件夾，當你執行
make html的時候，生成的html靜態文件都存放在這里 - _static：文件夾：圖片,js等存放地址
- _templates：文件夾:模板文件存放
- make.bat：bat腳本
- Makefile:編譯文件
- index.rst:索引文件,文章目錄大綱
- conf.py:配置文件
2.2編寫文章
在docs目錄下新建hello.rst,內容如下:
hello,world
=============
如果會markdown語法,無需學習rst語法,可參考文末語法轉換網站.
index.rst修改如下:
.. toctree::
:maxdepth: 2
hello
然后在docs目錄下執行 make html,進入 _build/html 目錄后用瀏覽器打開 index.html
2.3更改主題和添加md支持
vim conf.py #更改如下配置:
html_theme = "sphinx_rtd_theme"
extensions = ['recommonmark']
然后再次運行 make html 即可.
關於markdown的用法形式與rst一樣,直接更換后綴並在文件內已markdown語法寫內容即可.
3.與GitHub聯動
上傳代碼至GitHub倉庫,然后去 https://readthedocs.org/ 注冊賬號,並關聯GitHub倉庫.
然后需要在GitHub倉庫根目錄下,增加一個名稱為 .readthedocs.yml 的配置文件:
# .readthedocs.yml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
# Required
version: 2
# Build documentation in the docs/ directory with Sphinx
sphinx:
configuration: docs/conf.py
# Build documentation with MkDocs
#mkdocs:
# configuration: mkdocs.yml
# Optionally build your docs in additional formats such as PDF
formats:
- pdf
# Optionally set the version of Python and requirements required to build your docs
python:
version: 3.7
install:
- requirements: docs/requirements.txt
再去 docs 目錄下,新建一個名稱為 requirements.txt 的文件,在這個文件內增加你所使用的包名稱.
例如我的是:
sphinx
sphinx-rtd-theme
recommonmark
如果以上兩個文件不添加,那么自動構建出來的文章,與你在本地的生成的會不一致,因為 readthedocs 網站默認使用mkdocs來構建.