1.8.1. 安装

# 卸载 ubuntu 低版本 sphinx
sudo apt remove python3-sphinx

# 安装新版本 sphinx
conda install sphinx
pip install sphinx-autobuild
pip install sphinx_rtd_theme

1.8.2. 初始化文档

# 新建文档目录 doc
cd doc
sphinx-quickstart

# > Separate source and build directories (y/n) [n]: y
# > Project name: Notes
# > Author name(s): Li Runze
# > Project release []: v0.1
# > Project language [en]: zh_CN   (中文)

# 手动更新 html 文件
make html

# 自动更新 html 文件
sphinx-autobuild source build/html
sphinx-autobuild source build/html --port=0

# 自动更新 html 文件 (在 project1&2 路径下，同时打开多个项目)
sphinx-autobuild --port=0 --open-browser project1/docs project1/docs/build/html
sphinx-autobuild --port=0 --open-browser project2/docs project2/docs/build/html

# 如果报错无法找到 sphinx-autobuild, 需要进行软链接
# sudo ln -s {conda 安装的路径} {ubuntu 默认的路径}
sudo ln -s /home/lrz/opt/miniconda3/bin/sphinx-autobuild /usr/bin/sphinx-autobuild

# 在浏览器中打开 html 文件
# http://127.0.0.1:8000

1.8.3. 目录设置

编写 source/index.rst

 1文档标题
 2=================================
 3
 4.. toctree 目录
 5    maxdepth 目录层级
 6    numbered 章节自动编号层级
 7
 8.. toctree::
 9    :maxdepth: 2
10    :numbered: 3
11    :caption: 目录:
12
13    chapter-1/index
14    chapter-2/index
15
16    about
17
18索引与表格
19==================
20
21* :ref:`genindex`
22* :ref:`modindex`
23* :ref:`search`

1.8.4. 文档配置文件

修改 conf.py

 1# HTML 网页查看源码时，出现中文乱码
 2# 需要确保编码的匹配: 源码文件编码, 源码编码设置值, 浏览器编码 要一致
 3#   1) 源码文件 *.rst 采用 UTF-8 来支持不同特殊的字符
 4#   2) conf.py 中的编码为 UTF-8
 5source_encoding = 'utf-8-sig'
 6
 7#   3) 更改浏览器编码
 8#      Edge 浏览器可以使用插件 “网页编码修改 (Charset)”
 9
10# -------------------------------------------------------------------
11
12# 修改主题 Read the Docs Sphinx Theme
13# https://sphinx-rtd-theme.readthedocs.io/en/stable/index.html
14html_theme = 'sphinx_rtd_theme'
15extensions = [
16    ...,
17    'sphinx_rtd_theme'
18]
19html_static_path = ['_static']
20html_css_files = ['css/custom.css']
21
22# 配置主题
23# https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html
24
25html_theme_options = {
26    # Toc options
27    'collapse_navigation': True,
28    'sticky_navigation': False,
29    'navigation_depth': 4,
30    'includehidden': True,
31    'titles_only': False
32}
33
34# -------------------------------------------------------------------
35
36# 添加数学公式 (MathJax) 支持
37# https://docs.mathjax.org/en/latest/
38extensions = [
39    ...,
40    'sphinx.ext.mathjax'
41]
42
43# -------------------------------------------------------------------
44
45# 激活 图、表、代码块、公式 的自动编号
46# 仅针对 有 caption (图例) 标签的对象，该对象的 `numref` 同时生效
47numfig = True
48
49# 图例形式
50numfig_format = {
51    'figure': '图 %s',
52    'table': '表 %s',
53    'code-block': '代码 %s',
54    'section': '节 %s',
55}
56
57# 设置公式编号形式, 如 Eq.10.
58math_eqref_format = 'Eq.{number}'
59
60# 设置所有公式自动编号
61# 否则需自己标注 :label:
62math_number_all = False
63
64# 设置公式编号包含的章节层级
65math_numfig = True
66numfig_secnum_depth = 2

1.8.5. 数学公式

Sphinx Doc: Math directives

(1) 行内公式

在文本中写入 {:math:`\sum\limits_{k=1}^\infty \frac{1}{2^k} = 1`}

显式效果：\(\sum\limits_{k=1}^\infty \frac{1}{2^k} = 1\)

(2) 单独公式

1.. math::
2    e^{i\pi} + 1 = 0
3    :label: euler

公式 Eq.1.8.1 显式效果：

(1.8.1)\[e^{i\pi} + 1 = 0\]

交叉引用公式的标识为 :eq:`euler` 或 :math:numref:`euler。

内部换行公式：

1.. math::
2    (a + b)^2  &=  (a + b)(a + b) \\
3            &=  a^2 + 2ab + b^2
4    :label: 2line

公式 Eq.1.8.2 显式效果：

(1.8.2)\[\begin{split}(a + b)^2 &= (a + b)(a + b) \\ &= a^2 + 2ab + b^2\end{split}\]

矩阵形式的公式（如矩阵、大括号、多列公式等）：

 1.. math::
 2    & \left\{
 3        \begin{array}{ll}
 4            \phi_i^{(1)} &= \phi_i + \Delta t f_i(\phi_k|k=1,...,N) \\
 5            \phi_i^{(2)} &= \frac{3}{4} \phi_i + \frac{1}{4}
 6            [\phi_i^{(1)} + \Delta t f_i(\phi_k^{(1)}|k=1,...,N)] \\
 7            \hat \phi_i  &= \frac{1}{3} \phi_i + \frac{2}{3}
 8            [\phi_i^{(2)} + \Delta t f_i(\phi_k^{(2)}|k=1,...,N)]
 9        \end{array}
10    \right.
11    :label: multi-lines

公式 Eq.1.8.3 显式效果：

(1.8.3)\[\begin{split}& \left\{ \begin{array}{ll} \phi_i^{(1)} &= \phi_i + \Delta t f_i(\phi_k|k=1,...,N) \\ \phi_i^{(2)} &= \frac{3}{4} \phi_i + \frac{1}{4} [\phi_i^{(1)} + \Delta t f_i(\phi_k^{(1)}|k=1,...,N)] \\ \hat \phi_i &= \frac{1}{3} \phi_i + \frac{2}{3} [\phi_i^{(2)} + \Delta t f_i(\phi_k^{(2)}|k=1,...,N)] \end{array} \right.\end{split}\]

(3) 编号形式调整

链接：公式编号右侧对齐的设置 , 需要自定义 css 文件。

在 _static/css/cutsom.css 中写入：

.math {
   text-align: left;
}

.eqno {
   float: right;
}

1.8.6. 图片

图片格式参见 reStructuredText Images and Figures Examples 。

1.. _FigureExample:
2.. figure:: example.jpg
3    :width: 70 %
4    :align: center
5
6    示例图片

图 1.8.1 显式效果：

../../_images/example.jpg

图 1.8.1 示例图片