使用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