sphinx快速入門

簡介

sphinx是一個用於快速生成文檔的工具，很是適合生成Python文檔。

它具備如下優勢：

• 支持多種輸出格式， 如html，Latex，ePub等。

• 豐富的擴展

• 結構化文檔

• 自動索引

• 支持語法高亮

sphinx使用reStructuredtext做爲它的標記語言。

安裝

使用pip進行安裝：

pip install sphinx

設置源文件目錄

包含.rst文件的根目錄稱之爲源文件目錄，目錄中還包含sphinx的配置文件conf.py。

進入源文件目錄，執行如下命令，會指引用戶配置整個項目：

sphinx-quickstart

定義文件結構

執行上述命令以後，sphinx會在源文件目錄中自動生成conf.py文件以及index.rst。index.rst稱之爲主文檔，它被sphinx做爲歡迎頁面。

index.rst中包含了目錄樹指令toctree，sphinx使用它連接其餘子文檔。

toctree指令的初始值爲空：

.. toctree::
   :maxdepth: 2

接下來就能夠給它添加子文檔的連接了，直接使用文檔的名稱便可，省略掉文件後綴，若是是多級目錄，則使用/分隔開。

.. toctree::
   :maxdepth: 2

   intro
   tutorial
   chapter/doc1
   ...

接着咱們就能夠建立上面列出的文件並添加相應內容了，sphnix會自動將這些文檔的章節標題插入到doctree指令的位置。

添加內容

在sphinx源文件中，使用reStructuredText標記語言進行文檔編寫，除此以外，sphinx還格外提供了一些指令。

具體能夠參考

reStructuredText Primer 以及
Sphinx Markup Constructs

生成文檔

使用下面的命令生成文檔：

$ sphinx-build -b html sourcedir builddir

sourcedir指源文件目錄，生成的文檔放置在builddir指定的目錄中。

實際上還有一個更簡便的方法，sphinx-quickstart生成了一個make.bat文件，能夠直接運行這個腳本：

make html

上述命令會直接在源文件目錄中生成文檔。

對象文檔

sphinx的設計初衷之一就是更容易生成任何域中對象的文檔，域指不少對象的集合，這些對象中還包含了相應的文檔註釋。

最主要的域是Python域， 例如python內置函數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.)
　　
指令參數是咱們須要描述的對象，內容是咱們編寫的文檔註釋。因爲Python是默認的域，因此並不須要特別指出所屬的域來。

.. function:: enumerate(sequence[, start=0])

   ...

sphinx還提供了一些指令用於生成其餘對象類型的文檔。例如py:class以及py:method

基本配置

sphinx經過conf.py進行配置，conf.py使用python語法，默認以utf-8編碼保存。具體配置請查看 The build configuration file。

自動生成文檔註釋

sphinx支持從python源代碼中提取文檔註釋信息，而後生成文檔，咱們將這稱之爲autodoc。

爲了使用autodoc，首先須要在配置文件的extensions選項中添加'sphinx.ext.autodoc'。而後咱們就可使用autodoc的指令了。

例如，生成函數io.open()的文檔，只須要在rst文件中添加以下語句：

.. autofunction:: io.open

也能夠直接生成整個類的文檔：

.. automodule:: io
   :members:

爲了提取文檔註釋，autodoc須要導入註釋所在的模塊。所以須要在sys.path中設置好模塊的路徑。

設置主題

推薦使用readthedoc使用的主題，美觀又簡潔大方。
首先安裝主題庫：

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()]

簡書地址