利用Sphinx为项目生成文档

1、查看 python 版本

在命令行中输入 python -V，显示版本信息，表明安装成功。

C:\Users\Admin>python -V
Python 3.7.3

2、查看 pip 版本

查看 pip 版本

C:\Users\Admin>pip -V
pip 19.0.3 from d:\python37\lib\site-packages\pip (python 3.7)

3、安装 sphinx

留意从官方下载包会很慢，可以从国内镜像下载，让python pip使用国内镜像：

C:\Users\Admin>pip install -i https://mirrors.aliyun.com/pypi/simple/ -U sphinx

之后，将开始远程下载并安装。

执行make html命令可能会失败，可以按提示继续安装，例如：

D:\workspace\doc\doc-developer>make html
Running Sphinx v3.2.1
loading translations [zh_CN]... done

Extension error:
Could not import extension sphinx_markdown_tables (exception: No module named 'sphinx_markdown_tables')

提示sphinx_markdown_tables模块，继续安装该模块：pip install -i https://mirrors.aliyun.com/pypi/simple/ -U sphinx_markdown_tables

可能会提示没有以下模块或命令，继续安装：

pip install -i https://mirrors.aliyun.com/pypi/simple/  -U sphinx_rtd_theme
pip install -i https://mirrors.aliyun.com/pypi/simple/  -U sphinx_markdown_tables
pip install -i https://mirrors.aliyun.com/pypi/simple/  -U recommonmark
pip install -i https://mirrors.aliyun.com/pypi/simple/  -U sphinxprettysearchresults

4、后续步骤

可参考https://www.jianshu.com/p/49066dc2ab24

D:\doc>sphinx-quickstart
Welcome to the Sphinx 3.2.1 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: doc
> Author name(s): admin
> Project release []: 1.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

Creating file D:\doc\source\conf.py.
Creating file D:\doc\source\index.rst.
Creating file D:\doc\Makefile.
Creating file D:\doc\make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file D:\doc\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.