- git 仓库
https://sphinx-themes.org/sample-sites/sphinx-materialdesign-theme/index.html
这里以 Ubuntu 为例（其他 Linux 发行版、MacOS 或 Windows 也行），首先安装 Python3、Git、Make 等基础软件。
sudo apt install git
sudo apt install make
sudo apt install python3
sudo apt install python3-pip jupyter
然后安装最新版本的 Sphinx 及依赖。
sudo pip3 install -U Sphinx
为了完成本示例，还需要安装以下软件包。
sudo pip3 install sphinx-autobuild
sudo pip3 install sphinx_rtd_theme
sudo pip3 install recommonmark
sudo pip3 install sphinx_markdown_tables
sudo pip install sphinx_materialdesign_theme
sudo pip install mxtheme
sudo pip3 install jieba nbsphinx ipython awscli
我们以建立 diary 日记文档系统为例，先创建并进入 diary 文件夹（后续所有操作都在该文件夹内）。执行 sphinx-quickstart 构建项目框架，将会出现如下对话窗口。
欢迎使用 Sphinx 3.2.1 快速配置工具。
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.
> 独立的源文件和构建目录（y/n） [n]:
首先，询问你是否要创建独立的源文件和构建目录。实际上对应两种目录结构，一种是在根路径下创建“_build”目录，另一种是在根路径下创建“source”和“build”两个独立的目录，前者用于存放文档资源，后者用于保存构建生成的各种文件。根据个人喜好选择即可，比如我更倾向于独立目录，因此输入 y。
接着，需要输入项目名称、作者等信息。
The project name will occur in several places in the built documentation.
> 项目名称: diary
> 作者名称: Rudy
> 项目发行版本 []: v1
然后，可以设置项目的语言，我们这里选择简体中文。
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.
> 项目语种 [en]: zh_CN
OK，项目创建完成！（两种目录结构分别如下）
c
-
Makefile：可以看作是一个包含指令的文件，在使用 make 命令时，可以使用这些指令来构建文档输出。 -
build：生成的文件的输出目录。 -
make.bat：Windows 用命令行。 -
_static：静态文件目录，比如图片等。 -
_templates：模板目录。 -
conf.py：存放 Sphinx 的配置，包括在sphinx-quickstart时选中的那些值，可以自行定义其他的值。 -
index.rst：文档项目起始文件。
此时我们在 diary 目录中执行 make html，就会在 build/html 目录生成 html 相关文件。
image
在浏览器中打开 index.html，将会看到如下页面。
[图片上传失败...(image-87f7be-1611248346693)]
当然，直接访问 html 文件不是很方便，所以我们借助 sphinx-autobuild 工具启动 HTTP 服务。
sphinx-autobuild source build/html
默认启动 8000 端口，在浏览器输入http://127.0.0.1:8000 。
