Sphinx 自動(dòng)化文檔

目錄

文章目錄

目錄

Sphinx

入門(mén)

reStructuredText 語(yǔ)法格式

標(biāo)題、列表、正文、要點(diǎn)

表格

代碼塊

引用其他模塊文件

引用靜態(tài)圖片

Sphinx

官方網(wǎng)站：https://www.sphinx.org.cn/

它具有以下突出特性：

輸出格式：HTML（包括 Windows 的 HTML 幫助文件）、LaTex（可以打印為 PDF）、epub（流行的電子書(shū)格式）、Texinfo、manual pages（man 手冊(cè)）、plain Text（純文本）。

廣泛的交叉引用：語(yǔ)義標(biāo)記和函數(shù)，類，引用，詞匯表術(shù)語(yǔ)和類似信息的自動(dòng)鏈接。

分層架構(gòu)：輕松定義文檔樹(shù)，自動(dòng)鏈接到平級(jí)，上級(jí)和下級(jí)。

自動(dòng)索引：一般索引以及特定于語(yǔ)言的模塊索引。

代碼高亮：使用Pygments熒光筆自動(dòng)突出顯示。

擴(kuò)展：自動(dòng)測(cè)試代碼片段，包含 Python 模塊（API 文檔）中的文檔字符串等。

豐富的拓展：用戶在第二個(gè)存儲(chǔ)庫(kù)中貢獻(xiàn)了 50 多個(gè)擴(kuò)展，其中大多數(shù)可以從 PyPI 安裝。

入門(mén)

安裝：Sphinx 依賴 Python2.4 及以上版本。

pip3 install -U sphinx

1

創(chuàng)建文檔項(xiàng)目：在項(xiàng)目的根目錄下創(chuàng)建 doc 子目錄，并執(zhí)行文檔創(chuàng)建指令，期間你需要交互輸入一些配置。

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

配置：創(chuàng)建好文檔項(xiàng)目之后，可以看見(jiàn)一下文件或子目錄：

Makefile：在使用 make 命令時(shí)，可以使用這些指令（e.g. sphinx-build）來(lái)構(gòu)建文檔輸出。

_build：這是觸發(fā)特定輸出后用來(lái)存放所生成的文件的目錄。

_static：所有不屬于源代碼（e.g. 圖片）一部分的文件均存放于此處，稍后會(huì)在構(gòu)建目錄中將它們鏈接在一起。

conf.py：用于存放 Sphinx 的配置值，包括在終端執(zhí)行 sphinx-quickstart時(shí)選中的那些值。

index.rst：文檔項(xiàng)目的 root 目錄。如果將文檔劃分為其他文件，該目錄會(huì)連接這些文件。

編寫(xiě)文檔：在 index.rst 文件中的主標(biāo)題之后，有一個(gè)內(nèi)容清單，其中包括 toctree 聲明，它將所有文檔鏈接都匯集到 Index。例如：

# 我們想將一個(gè)新文件添加到文檔中，并打算將其命名為 example.rst。 Contents: .. toctree:: :maxdepth: 2 example

1

2

3

4

5

6

7

8

注：example.rst 的內(nèi)容如下

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

生成文檔：運(yùn)行 make 命運(yùn)，并將 HTML 指定為輸出格式。可直接將該輸出用作網(wǎng)站，因?yàn)樗松傻乃袃?nèi)容，包括 JavaScript 和 CSS 文件。

$ make html docs run-test: commands[0] | sphinx-build -W -b html doc/source doc/build/html 正在運(yùn)行 Sphinx v2.4.3 正在加載翻譯 [zh_CN]... 完成 制作輸出目錄... 完成 構(gòu)建 [mo]： 0 個(gè) po 文件的目標(biāo)文件已過(guò)期 構(gòu)建 [html]： 1 個(gè)源文件的目標(biāo)文件已過(guò)期 更新環(huán)境: [新配置] 已添加 1，0 已更改，0 已移除 閱讀源... [100%] index 查找當(dāng)前已過(guò)期的文件... 沒(méi)有找到 pickling環(huán)境... 完成 檢查一致性... 完成 準(zhǔn)備文件... 完成 寫(xiě)入輸出... [100%] index generating indices... genindex完成 writing additional pages... search完成 復(fù)制靜態(tài)文件... ... 完成 copying extra files... 完成 dumping search index in Chinese (code: zh)... 完成 dumping object inventory... 完成 構(gòu)建 成功. HTML 頁(yè)面保存在 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

生成靜態(tài)網(wǎng)頁(yè)：隨著我們完成前面的操作，從兩個(gè)文件中生成 HTML 之后，我們就擁有一個(gè)完整的靜態(tài)頁(yè)面網(wǎng)站。使用瀏覽器訪問(wèn) build/html 目錄下的 index.html 文件

添加圖片等靜態(tài)文件：只要將靜態(tài)文件放置 _static 目錄（Sphinx 在創(chuàng)建文檔布局時(shí)創(chuàng)建了該目錄）中，就可以輕松地對(duì)其進(jìn)行引用。。example.rst 的靜態(tài)清單如下：

.. image:: _static/system_activity.jpg

1

修改皮膚：sphinx 默認(rèn)提供了好多可選的皮膚，我們可以通過(guò)修改 conf.py 調(diào)整，比如：

html_theme = "classic"

1

使用 sphinx_rtd_theme 皮膚：

安裝

pip3 install sphinx_rtd_theme

1

- 配置

1

# conf.py html_theme = 'sphinx_rtd_theme'

1

2

3

- 重新構(gòu)建

1

make html

1

reStructuredText 語(yǔ)法格式

標(biāo)題、列表、正文、要點(diǎn)

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:參數(shù),類型,含義 :widths:2,2,5 test1,String,這里是測(cè)試的第一行 test2,int,這里是測(cè)試的第二行

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

點(diǎn)擊跳轉(zhuǎn)

調(diào)用 :ref:`點(diǎn)擊這里跳轉(zhuǎn)`

1

引用靜態(tài)圖片

.. image:: _static/system_activity.jpg

1

HTML Sphinx

版權(quán)聲明：本文內(nèi)容由網(wǎng)絡(luò)用戶投稿，版權(quán)歸原作者所有，本站不擁有其著作權(quán)，亦不承擔(dān)相應(yīng)法律責(zé)任。如果您發(fā)現(xiàn)本站中有涉嫌抄襲或描述失實(shí)的內(nèi)容，請(qǐng)聯(lián)系我們jiasou666@gmail.com 處理，核實(shí)后本網(wǎng)站將在24小時(shí)內(nèi)刪除侵權(quán)內(nèi)容。