Sphinx + Read the docs theme

前言:

使用Sphinx 生成文檔和使用 Read The Docs 的 readthedocs/sphinx_rtd_theme，假設是在Windows上運行並已安裝好 python，可以執行python的 pip命令

1. 通過 pip命令安裝 sphinx 和 sphinx_rtd_theme

pip install -U Sphinx
pip install sphinx-rtd-theme

2. 在一個系統中的一個空的文件夾中運行: 如我在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格式的文檔

3. 在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的說明

4. 生成 html 格式的文檔

命令行 進入 Sphinx 項目，運行

make html

or

make.bat html 

---

如果需要發布到 RTD官網

1. 編譯失敗，如在編譯時遇到以下錯誤

Sphinx error: master file [..]/checkouts/latest/contents.rst not found

修復方法是: 修改 sphinx項目的conf.py 添加以下的一行:

master_doc = 'index'

References

1. 技術文檔編寫利器：Sphinx+Read the Docs
2. Getting Started
3. Read the Docs Sphinx Theme
4. Sphinx error: master file ../checkouts/latest/contents.rst not found
5. Removing “Edit on …” Buttons from Documentation 隱藏RTD上的 "Edit on Github"信息