資訊專欄INFORMATION COLUMN
摘要：簡(jiǎn)介是一個(gè)用于快速生成文檔的工具，非常適合生成文檔。稱之為主文檔，它被作為歡迎頁(yè)面。由于是默認(rèn)的域，所以并不需要特別指出所屬的域來(lái)。自動(dòng)生成文檔注釋支持從源代碼中提取文檔注釋信息，然后生成文檔，我們將這稱之為。
簡(jiǎn)介
sphinx是一個(gè)用于快速生成文檔的工具，非常適合生成Python文檔。
它具有以下優(yōu)點(diǎn)：
支持多種輸出格式， 如html，Latex，ePub等。
豐富的擴(kuò)展
結(jié)構(gòu)化文檔
自動(dòng)索引
支持語(yǔ)法高亮
sphinx使用reStructuredtext作為它的標(biāo)記語(yǔ)言。
安裝使用pip進(jìn)行安裝：
pip install sphinx設(shè)置源文件目錄
包含.rst文件的根目錄稱之為源文件目錄，目錄中還包含sphinx的配置文件conf.py。
進(jìn)入源文件目錄，執(zhí)行以下命令，會(huì)指引用戶配置整個(gè)項(xiàng)目：
sphinx-quickstart定義文件結(jié)構(gòu)
執(zhí)行上述命令之后，sphinx會(huì)在源文件目錄中自動(dòng)生成conf.py文件以及index.rst。index.rst稱之為主文檔，它被sphinx作為歡迎頁(yè)面。
index.rst中包含了目錄樹(shù)指令toctree，sphinx使用它鏈接其他子文檔。
toctree指令的初始值為空：
.. toctree:: :maxdepth: 2
接下來(lái)就可以給它添加子文檔的鏈接了，直接使用文檔的名稱即可，省略掉文件后綴，如果是多級(jí)目錄，則使用/分隔開(kāi)。
.. toctree:: :maxdepth: 2 intro tutorial chapter/doc1 ...
接著我們就可以創(chuàng)建上面列出的文件并添加相應(yīng)內(nèi)容了，sphnix會(huì)自動(dòng)將這些文檔的章節(jié)標(biāo)題插入到doctree指令的位置。
添加內(nèi)容在sphinx源文件中，使用reStructuredText標(biāo)記語(yǔ)言進(jìn)行文檔編寫(xiě)，除此之外，sphinx還格外提供了一些指令。
具體可以參考
生成文檔reStructuredText Primer 以及
Sphinx Markup Constructs
使用下面的命令生成文檔：
$ sphinx-build -b html sourcedir builddir
sourcedir指源文件目錄，生成的文檔放置在builddir指定的目錄中。
實(shí)際上還有一個(gè)更簡(jiǎn)便的方法，sphinx-quickstart生成了一個(gè)make.bat文件，可以直接運(yùn)行這個(gè)腳本：
make html
上述命令會(huì)直接在源文件目錄中生成文檔。
對(duì)象文檔sphinx的設(shè)計(jì)初衷之一就是更容易生成任何域中對(duì)象的文檔，域指很多對(duì)象的集合，這些對(duì)象中還包含了相應(yīng)的文檔注釋。
最主要的域是Python域， 例如python內(nèi)置函數(shù)enumerate()的注釋文檔如下所示：
.. py:function:: enumerate(sequence[, start=0]) Return an iterator that yields tuples of an index and an item of the *sequence*. (And so on.)
它將被渲染成如下格式：
enumerate(sequence[, start=0])
Return an iterator that yields tuples of an index and an item of the sequence. (And so on.)
指令參數(shù)是我們需要描述的對(duì)象，內(nèi)容是我們編寫(xiě)的文檔注釋。由于Python是默認(rèn)的域，所以并不需要特別指出所屬的域來(lái)。
.. function:: enumerate(sequence[, start=0]) ...
sphinx還提供了一些指令用于生成其他對(duì)象類型的文檔。例如py:class以及py:method
基本配置sphinx通過(guò)conf.py進(jìn)行配置，conf.py使用python語(yǔ)法，默認(rèn)以u(píng)tf-8編碼保存。具體配置請(qǐng)查看 The build configuration file。
自動(dòng)生成文檔注釋sphinx支持從python源代碼中提取文檔注釋信息，然后生成文檔，我們將這稱之為autodoc。
為了使用autodoc，首先需要在配置文件的extensions選項(xiàng)中添加"sphinx.ext.autodoc"。然后我們就可以使用autodoc的指令了。
例如，生成函數(shù)io.open()的文檔，只需要在rst文件中添加如下語(yǔ)句：
.. autofunction:: io.open
也可以直接生成整個(gè)類的文檔：
.. automodule:: io :members:
為了提取文檔注釋，autodoc需要導(dǎo)入注釋所在的模塊。因此需要在sys.path中設(shè)置好模塊的路徑。
設(shè)置主題推薦使用readthedoc使用的主題，美觀又簡(jiǎn)潔大方。
首先安裝主題庫(kù)：
pip install sphinx_rtd_theme
然后配置conf.py:
import sphinx_rtd_theme html_theme = "sphinx_rtd_theme" html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
簡(jiǎn)書(shū)地址
文章版權(quán)歸作者所有，未經(jīng)允許請(qǐng)勿轉(zhuǎn)載,若此文章存在違規(guī)行為，您可以聯(lián)系管理員刪除。
轉(zhuǎn)載請(qǐng)注明本文地址：http://specialneedsforspecialkids.com/yun/38214.html
摘要：一介紹與好處介紹本身是一個(gè)中文檢索索引技術(shù)索引主鍵唯一普通全文是俄羅斯人開(kāi)發(fā)一款速度效率非常高的索引技術(shù)是來(lái)替代全文索引的本身的全文索引技術(shù)特性表現(xiàn)一般，一般數(shù)據(jù)庫(kù)使用全文索引都不是使用本身的，都需要借助第方索引技術(shù)支持，搜索引擎百 一．sphinx介紹與好處 介紹 sphinx本身是一個(gè)中文檢索索引技術(shù) mysql索引： 主鍵、唯一、普通、全文(match/agaisnt)sphi...
摘要：使用第二版的擴(kuò)展匹配模式對(duì)查詢進(jìn)行匹配強(qiáng)制使用下文所述的完整掃描模式來(lái)對(duì)查詢進(jìn)行匹配。并且可以在服務(wù)器端設(shè)定當(dāng)前查詢的結(jié)果集大小，另有一個(gè)閾值，當(dāng)找到的匹配項(xiàng)達(dá)到這個(gè)閥值時(shí)就停止搜索。 Sphinx 簡(jiǎn)介 Sphinx 說(shuō)明我這就不多說(shuō)了，有興趣的朋友可以點(diǎn)擊 編譯安裝sphinx-0.9.9全文檢索 去看詳情~！ sphinx中文手冊(cè) 創(chuàng)建Sphinx索引 source src_bl...
摘要：使用第二版的擴(kuò)展匹配模式對(duì)查詢進(jìn)行匹配強(qiáng)制使用下文所述的完整掃描模式來(lái)對(duì)查詢進(jìn)行匹配。并且可以在服務(wù)器端設(shè)定當(dāng)前查詢的結(jié)果集大小，另有一個(gè)閾值，當(dāng)找到的匹配項(xiàng)達(dá)到這個(gè)閥值時(shí)就停止搜索。 Sphinx 簡(jiǎn)介 Sphinx 說(shuō)明我這就不多說(shuō)了，有興趣的朋友可以點(diǎn)擊 編譯安裝sphinx-0.9.9全文檢索 去看詳情~！ sphinx中文手冊(cè) 創(chuàng)建Sphinx索引 source src_bl...
閱讀 5739·2021-11-24 10:25
閱讀 2689·2021-11-16 11:44
閱讀 3843·2021-10-11 11:09
閱讀 3172·2021-09-02 15:41
閱讀 3256·2019-08-30 14:14
閱讀 2271·2019-08-29 14:10
閱讀 2345·2019-08-29 11:03
閱讀 1125·2019-08-26 13:47
