Sphinx 自动化文档

目录

文章目录

目录

Sphinx

入门

reStructuredText 语法格式

标题、列表、正文、要点

表格

代码块

引用其他模块文件

引用静态图片

Sphinx

官方网站：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

1

创建文档项目：在项目的根目录下创建 doc 子目录，并执行文档创建指令，期间你需要交互输入一些配置。

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

配置：创建好文档项目之后，可以看见一下文件或子目录：

Makefile：在使用 make 命令时，可以使用这些指令（e.g. sphinx-build）来构建文档输出。

_build：这是触发特定输出后用来存放所生成的文件的目录。

_static：所有不属于源代码（e.g. 图片）一部分的文件均存放于此处，稍后会在构建目录中将它们链接在一起。

conf.py：用于存放 Sphinx 的配置值，包括在终端执行 sphinx-quickstart时选中的那些值。

index.rst：文档项目的 root 目录。如果将文档划分为其他文件，该目录会连接这些文件。

编写文档：在 index.rst 文件中的主标题之后，有一个内容清单，其中包括 toctree 声明，它将所有文档链接都汇集到 Index。例如：

# 我们想将一个新文件添加到文档中，并打算将其命名为 example.rst。 Contents: .. toctree:: :maxdepth: 2 example

1

2

3

4

5

6

7

8

注：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!

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

生成文档：运行 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 目录。

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

生成静态网页：随着我们完成前面的操作，从两个文件中生成 HTML 之后，我们就拥有一个完整的静态页面网站。使用浏览器访问 build/html 目录下的 index.html 文件

添加图片等静态文件：只要将静态文件放置 _static 目录（Sphinx 在创建文档布局时创建了该目录）中，就可以轻松地对其进行引用。。example.rst 的静态清单如下：

.. image:: _static/system_activity.jpg

1

修改皮肤：sphinx 默认提供了好多可选的皮肤，我们可以通过修改 conf.py 调整，比如：

html_theme = "classic"

1

使用 sphinx_rtd_theme 皮肤：

安装

pip3 install sphinx_rtd_theme

1

- 配置

1

# conf.py html_theme = 'sphinx_rtd_theme'

1

2

3

- 重新构建

1

make html

1

reStructuredText 语法格式

标题、列表、正文、要点

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!

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

表格

.. csv-table:: :header:参数,类型,含义 :widths:2,2,5 test1,String,这里是测试的第一行 test2,int,这里是测试的第二行

1

2

3

4

5

6

代码块

.. code-block:: xml public void test(){ throws new Exception("this is a test"); }

1

2

3

4

5

引用其他模块文件

.. toctree:: :macdepth: 3 module one module two

1

2

3

4

5

点击跳转

调用 :ref:`点击这里跳转`

1

引用静态图片

.. image:: _static/system_activity.jpg

1

HTML Sphinx

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。