2. sphinx 与 rst

2.1. sphinx

Important

当前使用的版本是：

1Sphinx                        4.5.0
2sphinx-rtd-theme              1.0.0
3sphinxcontrib-applehelp       1.0.2
4sphinxcontrib-devhelp         1.0.2
5sphinxcontrib-htmlhelp        2.0.0
6sphinxcontrib-jsmath          1.0.1
7sphinxcontrib-qthelp          1.0.3
8sphinxcontrib-serializinghtml 1.1.5

Note

在 mac 上安装 sphinx 5.2.3：

brew install sphinx-doc

发现自动安装了依赖 python@3.10 ，而不是用 系统已经安装好的 /usr/bin/python ，这就导致 sphinx-build 一直找不到 /usr/bin/pip 安装的 sphinx-rtd-theme ， 因此需要使用：

/opt/homebrew/Cellar/python@3.10/3.10.6_2/bin/python3.10 -m pip install sphinx-rtd-theme

来重新安装。添加环境变量：

echo 'export PATH="/opt/homebrew/opt/sphinx-doc/bin:$PATH"' >> ~/.zshrc

编译之后，本地查看 html 结果显示正常，但是 push 到 Github 发布之后，发现代码行号几乎紧贴代码本身，视觉效果很差。 没找到好的解决方法，只能手动降级 sphinx：

/opt/homebrew/Cellar/python@3.10/3.10.6_2/bin/python3.10 -m pip install sphinx==4.5

Note

如果修改了目录结构（新增、删除、改名、调换顺序等），最好重新 build 一次:

make clean
make html

否则目录总是会跳到以前的版本去。

2.2. rst 语法测试

makefile 语法高亮：

target ... : prerequisites ...
    command
    ...
    ...

下面是几个定义：

target

可以是一个object file（目标文件），也可以是一个执行文件，还可以是一个标签（label）。对 于标签这种特性，在后续的“伪目标”章节中会有叙述。

prerequisites

生成该target所依赖的文件和/或target

command

该target要执行的命令（任意的shell命令）

行内公式使用 math role ： \(a^2 + b^2 = c^2\) 。

行间公式：

\[\begin{split}(a + b)^2 &= (a + b)(a + b) \\ &= a^2 + 2ab + b^2\end{split}\]
\[X_k = \sum_{n=0}^{N-1} x_n e^{-{i 2\pi k \frac{n}{N}}} \qquad k = 0,\dots,N-1.\]

将高亮语言设置为 C ：

.. highlight:: c
    :linenothreshold: 1

测试 C:

1int a = 0;
2char c = 'c';
3printf("%c\n", c);

这里是 C++ :

1int main()
2{
3  int i;
4  int j;
5  cin >> i >> j;
6  cout << i << j << endl;
7  return 1;
8}
9// 主函数注释

斜体 text

将高亮语言设置为 python ：

1.. highlight:: python
2    :linenothreshold: 2

测试 python:

1import torch
2import numpy as np
3print "hello world"

这里也是 python （code）:

1def foo():
2    print "Love Python, Love FreeDome"
3    print "E文标点,.0123456789,中文标点,. "

如果数据库有问题, 执行下面的 SQL:

1-- Dumping data for table `item_table`
2INSERT INTO item_table VALUES (
30000000001, 0, 'Manual', '', '0.18.0',
4'This is the manual for Mantis version 0.18.0.\r\n\r\nThe Mantis manual is modeled after the [url=http://www.php.net/manual/en/]PHP Manual[/url]. It is authored via the \\"manual\\" module in Mantis CVS.  You can always view/download the latest version of this manual from [url=http://mantisbt.sourceforge.net/manual/]here[/url].',
5  '', 1, 1, 20030811192655);

下面的代码有高亮行：

1# 测试注释
2def foo():
3    print "Love Python, Love FreeDome"
4    print "E文标点,.0123456789,中文标点,. "

下面是 javescipt 的 rst 源码：

1.. code-block:: javascript
2    :linenos:
3
4    function whatever()
5    {
6        return "such color"
7    }

下面是 bash :

1cd home
2echo $PATH
3source ~/.bashrc
4ls -l
5mkdir filefolder
6cd ..

代码折叠功能需要自定义 _templates 。

\(\color{darkgreen}{Show/Hide\ Code}\)

 1class Solution(object):
 2    def canJump(self, nums):
 3        """
 4        https://leetcode.com/problems/jump-game/
 5        Each element in the array represents your maximum jump length at that position.
 6
 7        Input: [2,3,1,1,4]
 8        Output: true
 9        Explanation: Jump 1 step from index 0 to 1, then 3 steps to the last index.
10
11        :type nums: List[int]
12        :rtype: bool
13        """
14        if nums == []:
15            return False
16        if len(nums) == 1:
17            return True
18        return None

插入空行使用 | ，下面是两个空行。



这里有一个下载链接：lake

使用 sphinx.ext.graphviz 扩展，下面是一个无向图：

graph foo { "bar" -- "baz"; }

无向图

下面是一个有向图：

digraph foo { size = "4, 4"; main [shape=box]; /* 这是注释 */ main -> parse [weight=8]; parse -> execute; main -> init [style=dotted]; main -> cleanup; execute -> { make_string; printf} init -> make_string; edge [color=red]; // 设置生效 main -> printf [style=bold,label="100 times"]; make_string [label="make a\n字符串"]; node [shape=box,style=filled,color=".7 .3 1.0"]; execute -> compare; }

有向图

一行插入多张图：

pic1 <- -> pic2

多列列表使用 hlist ：

  • item1

  • item2

  • item3

  • item4

field list：

School

ustc

Year

1958

Addr

hefei, anhui

Me

fong

Todo

补充更多的语法测试内容。

Tip

VS Code 推荐使用插件：

  • reStructuredText Syntax highlighting（@Trond Snekvik）

  • RST Preview（@Thomas Haakon Townsend）

  • reStructuredText（@LeXtudio Inc.）

Hint

使用 sphinx.ext.graphviz 扩展需要安装 graphviz（brew 安装不要使用代理）：

brew install graphviz

然后设置环境变量（dot 的目录 which dot ）：

export PATH=$PATH:/opt/homebrew/bin

在配置文件 conf.py 中设置导出格式:

graphviz_output_format = 'svg'

Warning

编译的时候提示：

WARNING: html_static_path 入口 ‘_static’ 不存在

需要在 source 目录下新增一个 _static 目录。

2.3. 参考资料

  1. sphinx_rtd_theme 配置

  1. sphinx themes

  1. reStructuredText

  1. reStructuredText 域

  1. reStructuredText Directives

  1. reStructuredText(rst)快速入门语法说明

  1. 代码隐藏（自定义，_templates放在conf.py同目录下）

  1. 代码隐藏（安装扩展，全屏显示，体验不好）

  1. Sphinx + Github Page + Read the Docs

  1. latex 颜色

  1. graphviz

  1. How to add custom CSS or JavaScript to Sphinx documentation