使用readthedocs 發布 sphinx doc文檔

readthedocs 是由社區驅動的開源sphinx doc 托管服務，我們可以用來方便的構建以及發布文檔

這是一個簡單的demo 項目，使用了用的比較多的sphinx_rtd_theme 主題，主要是試用

注冊賬戶

sphinx 文檔需要讓readthedocs 托管，我們需要一個賬戶，注冊地址
https://readthedocs.org/ ，注冊很簡單，我們同時需要進行郵件驗證

簡單demo 項目

我們可以使用sphinx-quickstart 幫助我們生成簡單的測試doc

sphinx-quickstart 命令執行之后會有提示，按照提示操作即可

簡單操作參考：sphinx doc 簡單試用

配置readthedocs

我們可以在項目中添加配置，方便readthedocs 進行構建，比如我們需要依賴sphinx_rtd_theme 主題的配置
參考配置：.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: source/conf.py

​

# Build documentation with MkDocs

#mkdocs:

# configuration: mkdocs.yml

​

# Optionally build your docs in additional formats such as PDF and ePub

formats: all

​

# Optionally set the version of Python and requirements required to build your docs

python:

  version: 3.7

  install:

    - requirements: requirements.txt

 

requirements.txt 文件內容： 這個主要是添加了 sphinx_rtd_theme 主題的pip 依賴

sphinx_rtd_theme

使用readthedocs 托管sphinx doc

readthedocs 基於git 進行項目管理，我們需要將代碼給提交github ，或者類似的git 服務中

• 選擇手工導入項目

 

• 配置

 

 

• 進行文檔構建

 

• 構建效果

 

• 訪問內容
  我自己的地址：https://dalongrong.readthedocs.io/en/latest/
  內容：

 

提供的文檔下載服務：

 

說明

使用readthedocs 進行sphinx doc 的構建版本管理，是一個很不錯的方案，方便、靈活

參考資料

https://github.com/rongfengliang/sphinxdemo-docs
https://docs.readthedocs.io/en/stable/config-file/v2.html