目录
Sphinx
Sphinx 是一个工具，它使得创建一个智能而美丽的文档变得简单。作者是 Georg Brandl，基于 BSD 许可证。起初为写 Python 文档而诞生的 Sphinx，现在已经支持为各种语言生成软件开发文档。Sphinx 使用 reStructuredText 作为编写语言，也可以使用 Markdown+拓展库 的方式进行文档的编写。
官方网站：https://www.sphinx.org.cn/
它具有以下突出特性：
- 输出格式：HTML（包括 Windows 的 HTML 帮助文件）、LaTex（可以打印为 PDF）、epub（流行的电子书格式）、Texinfo、manual pages（man 手册）、plain Text（纯文本）。
- 广泛的交叉引用：语义标记和函数，类，引用，词汇表术语和类似信息的自动链接。
- 分层架构：轻松定义文档树，自动链接到平级，上级和下级。
- 自动索引：一般索引以及特定于语言的模块索引。
- 代码高亮：使用Pygments荧光笔自动突出显示。
- 扩展：自动测试代码片段，包含 Python 模块（API 文档）中的文档字符串等。
- 丰富的拓展：用户在第二个存储库中贡献了 50 多个扩展，其中大多数可以从 PyPI 安装。
入门
- 安装：Sphinx 依赖 Python2.4 及以上版本。
pip3 install -U sphinx- 创建文档项目：在项目的根目录下创建 doc 子目录，并执行文档创建指令，期间你需要交互输入一些配置。
$ sphinx-quickstart
mickeyfan$ sphinx-quickstart
欢迎使用 Sphinx 2.4.3 快速配置工具。
请输入接下来各项设置的值（如果方括号中指定了默认值，直接
按回车即可使用默认值）。
已选择根路径：.
布置用于保存 Sphinx 输出的构建目录，有两种选择。
一是在根路径下创建“_build”目录，二是在根路径下创建“source”
和“build”两个独立的目录。
> 独立的源文件和构建目录（y/n） [n]: y
项目名称会出现在文档的许多地方。
> 项目名称: 5G Provider
> 作者名称: fanguiju
> 项目发行版本 []: v1.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.
> 项目语种 [en]: zh_CN
创建文件 ./source/conf.py。
创建文件 ./source/index.rst。
创建文件 ./Makefile。
创建文件 ./make.bat。
完成：已创建初始目录结构。
你现在可以填写主文档文件 ./source/index.rst 并创建其他文档源文件了。 用 Makefile 构建文档，像这样：
make builder
此处的“builder”是支持的构建器名，比如 html、latex 或 linkcheck。-
配置：创建好文档项目之后，可以看见一下文件或子目录：
- Makefile：在使用
make命令时，可以使用这些指令（e.g.sphinx-build）来构建文档输出。 - _build：这是触发特定输出后用来存放所生成的文件的目录。
- _static：所有不属于源代码（e.g. 图片）一部分的文件均存放于此处，稍后会在构建目录中将它们链接在一起。
- conf.py：用于存放 Sphinx 的配置值，包括在终端执行
sphinx-quickstart时选中的那些值。 - index.rst：文档项目的 root 目录。如果将文档划分为其他文件，该目录会连接这些文件。
- Makefile：在使用
-
编写文档：在 index.rst 文件中的主标题之后，有一个内容清单，其中包括
toctree声明，它将所有文档链接都汇集到 Index。例如：
# 我们想将一个新文件添加到文档中，并打算将其命名为 example.rst。
Contents:
.. toctree::
:maxdepth: 2
example注：example.rst 的内容如下
This is a Title
===============
That has a paragraph about a main subject and is set when the '='
is at least the same length of the title itself.
Subject Subtitle
----------------
Subtitles are set with '-' and are required to have the same length
of the subtitle itself, just like titles.
Lists can be unnumbered like:
* Item Foo
* Item Bar
Or automatically numbered:
#. Item 1
#. Item 2
Inline Markup
-------------
Words can have *emphasis in italics* or be **bold** and you can define
code samples with back quotes, like when you talk about a command: ``sudo``
gives you super user powers!- 生成文档：运行
make命运，并将 HTML 指定为输出格式。可直接将该输出用作网站，因为它包含了生成的所有内容，包括 JavaScript 和 CSS 文件。
$ make html
docs run-test: commands[0] | sphinx-build -W -b html doc/source doc/build/html
正在运行 Sphinx v2.4.3
正在加载翻译 [zh_CN]... 完成
制作输出目录... 完成
构建 [mo]： 0 个 po 文件的目标文件已过期
构建 [html]： 1 个源文件的目标文件已过期
更新环境: [新配置] 已添加 1，0 已更改，0 已移除
阅读源... [100%] index
查找当前已过期的文件... 没有找到
pickling环境... 完成
检查一致性... 完成
准备文件... 完成
写入输出... [100%] index
generating indices... genindex完成
writing additional pages... search完成
复制静态文件... ... 完成
copying extra files... 完成
dumping search index in Chinese (code: zh)... 完成
dumping object inventory... 完成
构建 成功.
HTML 页面保存在 doc/build/html 目录。- 生成静态网页：随着我们完成前面的操作，从两个文件中生成 HTML 之后，我们就拥有一个完整的静态页面网站。使用浏览器访问 build/html 目录下的 index.html 文件
- 添加图片等静态文件：只要将静态文件放置 _static 目录（Sphinx 在创建文档布局时创建了该目录）中，就可以轻松地对其进行引用。。example.rst 的静态清单如下：
.. image:: _static/system_activity.jpg- 修改皮肤：sphinx 默认提供了好多可选的皮肤，我们可以通过修改 conf.py 调整，比如：
html_theme = "classic"- 使用 sphinx_rtd_theme 皮肤：
- 安装
pip3 install sphinx_rtd_theme- 配置# conf.py
html_theme = 'sphinx_rtd_theme'- 重新构建make htmlreStructuredText 语法格式
标题、列表、正文、要点
This is a Title
===============
That has a paragraph about a main subject and is set when the '='
is at least the same length of the title itself.
Subject Subtitle
----------------
Subtitles are set with '-' and are required to have the same length
of the subtitle itself, just like titles.
Lists can be unnumbered like:
* Item Foo
* Item Bar
Or automatically numbered:
#. Item 1
#. Item 2
Inline Markup
-------------
Words can have *emphasis in italics* or be **bold** and you can define
code samples with back quotes, like when you talk about a command: ``sudo``
gives you super user powers!表格
.. csv-table::
:header:参数,类型,含义
:widths:2,2,5
test1,String,这里是测试的第一行
test2,int,这里是测试的第二行代码块
.. code-block:: xml
public void test(){
throws new Exception("this is a test");
}引用其他模块文件
.. toctree::
:macdepth: 3
module one
module two点击跳转
调用 :ref:`点击这里跳转<file.key>`引用静态图片
.. image:: _static/system_activity.jpg相关阅读：