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