前言:
使用Sphinx 生成文档和使用 Read The Docs 的 readthedocs/sphinx_rtd_theme，假设是在Windows上运行并已安装好 python，可以执行python的 pip命令
- 通过 pip命令安装 sphinx 和 sphinx_rtd_theme
pip install -U Sphinx pip install sphinx-rtd-theme
- 在一个系统中的一个空的文件夹中运行: 如我在D 盘中新建了一个名字为
sphinx的文件夹
sphinx-quickstart
D:\>mkdir sphinx-study D:\>cd sphinx-study D:\sphinx-study>sphinx-quickstart Welcome to the Sphinx 2.2.0 quickstart utility. 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. > Separate source and build directories (y/n) [n]: y The project name will occur in several places in the built documentation. > Project name: Study > Author name(s): wakasann > Project release []: 1.0.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. > Project language [en]: zh_CN Creating file .\source\conf.py. Creating file .\source\index.rst. Creating file .\Makefile. Creating file .\make.bat. Finished: An initial directory structure has been created. You should now populate your master file .\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. D:\sphinx-study>
从上面的末尾的提示，可以看到，可以通过make builder来编译文档，builder是如html,latex 或者linkcheck其中的一个支持的编译器。
如命令: make html 是生成html格式的文档
- 在Sphinx项目中使用sphinx-rtd-theme主题，将下面的配置项加到
conf.py文件中
import sphinx_rtd_theme
extensions = [
...
"sphinx_rtd_theme",
]
html_theme = "sphinx_rtd_theme"
来自 Read the Docs Sphinx Theme的README.md的说明
- 生成 html 格式的文档
命令行 进入 Sphinx 项目，运行
make html
or
make.bat html
如果需要发布到 RTD官网
- 编译失败，如在编译时遇到以下错误
Sphinx error: master file [..]/checkouts/latest/contents.rst not found
修复方法是: 修改 sphinx项目的conf.py 添加以下的一行:
master_doc = 'index'