使用 Sphinx 製作簡潔而又美觀的文檔

（點擊

上方藍字

，快速關注我們）

來源：Alfredo Deza 

ibm.com/developerworks/cn/opensource/os-sphinx-documentation/index.html

如有好文章投稿，請點擊 → 這裡了解詳情

簡介

Sphinx 是一種工具，它允許開發人員以純文本格式編寫文檔，以便採用滿足不同需求的格式輕鬆生成輸出。這在使用 Version Control System 追蹤變更時非常有用。純文本文檔對不同系統之間的協作者也非常有用。純文本是當前可以採用的最便捷的格式之一。

雖然 Sphinx 是用 Python 編寫的，並且最初是為 Python 語言文檔而創建，但它並不一定是以語言為中心，在某些情況下，甚至不是以程序員為中心。Sphinx 有許多用處，比如可以用它來編寫整本書！

突出顯示：默認情況下，Sphinx 會為 Python 突出顯示代碼，但它還允許定義其他編程語言，比如 C 和 Ruby。

可以將 Sphinx 想像成為一種文檔框架：它會抽象化比較單調的部分，並提供自動函數來解決一些常見問題，比如突出顯示標題索引和特殊代碼（在顯示代碼示例時），以及突出顯示適當的語法。

要求

您應該能輕車熟路地使用 Linux? 或 UNIX? 終端（也稱為控制台或終端模擬器），因為命令行界面是與 Sphinx 進行互動的主要方式。

您需要安裝 Python。在所有主要的 Linux 發行版和一些基於 UNIX 的操作系統（如 Mac OSX）上預先安裝 Python 並做好使用它的準備。要確定您已經安裝了 Python 並且安裝的是有效版本，請運行 清單 1 中的代碼。

清單 1. 檢查 Python 的版本

$

python

--

version

Python

2.6.1

語法

Sphinx 使用 reStructuredText 標記語法（和其他一些語法）來提供文檔控制。如果您之前編寫過純文本文件，那麼您可能非常了解精通 Sphinx 所需的語法。

標記允許為適當的輸出實現文本的定義和結構。開始之前，請參見 清單 2 中的一個小的標記語法示例。

清單 2. Sphinx 標記語法示例

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

!

正如您所看到的，純文本格式的語法非常容易讀懂。在創建特定格式（如 HTML）時，標題會成為主要目標，其字體會比副標題大一些（理應如此），並且會對編號列表進行適當的編號。您已經擁有一些非常強大的功能。添加更多的項或更改編號列表中的順序不會影響到編號，而通過替換使用的下劃線可以改變標題的重要性。

安裝和配置

安裝是通過命令行進行的，非常簡單明了，如 清單 3 所示。

清單 3. 安裝 Sphinx

$

easy_install sphinx

Searching

for

sphinx

Reading

http

://

pypi

.

python

.

org

/

simple

/

sphinx

/

Reading

http

://

sphinx

.

pocoo

.

org

/

Best

match

:

Sphinx

1.0.5

Downloading

http

://

pypi

.

python

.

org

/

packages

/

[...]

Processing

Sphinx

-

1.0.5

-

py2

.

5.egg

[...]

Finished processing dependencies

for

sphinx

為了簡便起見， 清單 3 中的內容有所縮減，但它提供了在一個在安裝 Sphinx 時應執行的操作的示例。

框架使用了一個目錄結構來分離源文件（純文本文件）和構建（指生成的輸出）。例如，如果使用 Sphinx 從文檔源中生成一個 PDF，那麼該文件會放置在構建目錄中。您可以更改此行為，但為了獲得一致性，我們還是保留了默認格式。

讓我們快速啟動 清單 4 的一個新的文檔項目，系統會通過一些問題提示您如何操作。請按下 Enter 鍵接受所有的默認值。

清單 4. 執行 sphinx-quickstart

$

sphinx

-

quickstart

Welcome to the

Sphinx

1.0.5

quickstart

utility

.

Please enter values

for

the following settings

(

just press Enter to

accept

a

default

value

,

if

one

is

given

in

brackets

).

[...]

我選擇 「My Project」 作為項目名稱，該名稱會在多處被引用。您可以隨意選擇不同的名稱。

運行 sphinx-quickstart 命令後，在工作目錄中會出現類似 清單 5 的文件。

清單 5. 工作目錄的列表

.

├──

Makefile

├──

_build

├──

_static

├──

conf

.

py

└──

index

.

rst

讓我們詳細研究一下每個文件。

• 
  

  Makefile：編譯過代碼的開發人員應該非常熟悉這個文件，如果不熟悉，那麼可以將它看作是一個包含指令的文件，在使用 make 命令時，可以使用這些指令來構建文檔輸出。



• 
  

  _build：這是觸發特定輸出後用來存放所生成的文件的目錄。



• 
  

  _static：所有不屬於源代碼（如圖像）一部分的文件均存放於此處，稍後會在構建目錄中將它們鏈接在一起。



• 
  

  conf.py：這是一個 Python 文件，用於存放 Sphinx 的配置值，包括在終端執行 sphinx-quickstart時選中的那些值。



• 
  

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

入門指南

此時，我們已經正確安裝了 Sphinx，查看了默認結構，並了解了一些基本語法。不要直接開始編寫文檔。缺乏布局和輸出方面的知識會讓您產生混淆，可能耽誤您的整個進程。

現在來深入了解一下 index.rst 文件。它包含大量的信息和其他一些複雜的語法。為了更順利地完成任務並避免干擾，我們將合併一個新文件，將它列在主要章節中。

在 index.rst 文件中的主標題之後，有一個內容清單，其中包括 toctree 聲明。toctree 是將所有文檔彙集到文檔中的中心元素。如果有其他文件存在，但沒有將它們列在此指令下，那麼在構建的時候，這些文件不會隨文檔一起生成。

我們想將一個新文件添加到文檔中，並打算將其命名為 example.rst。還需要將它列在 toctree 中，但要謹慎操作。文件名後面需要有一個間隔，這樣文件名清單才會有效，該文件不需要文件擴展名（在本例中為 .rst）。 清單 6 顯示該列表的外觀。在文件名距離左邊距有三個空格的距離，maxdepth 選項後面有一個空白行。

清單 6. index.rst 中的 toctree 示例

Contents

:

..

toctree

::

   :

maxdepth

:

2

  

example

此時，不用擔心其他選項。目前，注意到了有一個列出其他單獨的文件的索引文件，該文件可存儲有效文檔，因此，該列表有一定的順序和空格，才能使該列表變得有效。

還記得 清單 2 中的示例語法嗎? 請複製該示例，將它粘貼到 example.rst 文件中並保存它。現在我們準備生成輸出。

運行 make 命運，並將 HTML 指定為輸出格式。可直接將該輸出用作網站，因為它包含了生成的所有內容，包括 JavaScript 和 CSS 文件。請參見 清單 7 。

清單 7. make html 命令的輸出

$

make html

sphinx

-

build

-

b

html

-

d

_build

/

doctrees

  

.

_build

/

html

Making output

directory

...

Running Sphinx

v1

.

0.5

loading pickled

environment

...

not

yet created

building

[

html

]

:

targets

for

2

source files that are out of date

updating

environment

:

2

added

,

0

changed

,

0

removed

reading

sources

...

[

100

%

]

index

looking

for

now

-

outdated

files

...

none

found

pickling

environment

...

done

checking

consistency

...

done

preparing

documents

...

done

writing

output

...

[

100

%

]

index

writing additional

files

...

genindex search

copying static

files

...

done

dumping search

index

...

done

dumping object

inventory

...

done

build

succeeded

.

Build

finished

.

The HTML pages are

in

_build

/

html

.

如果您對 make 命令提供的其他選項感興趣，請參見 清單 8，將幫助標誌傳至此處，並查看完整的描述。

清單 8. 列示 make 選項

$

make

-

h

Usage

:

make

[

options

]

[

target

]

...

Options

:

[...]

生成靜態網站

隨著我們完成第一步操作，從兩個文件中生成 HTML 之後，我們就擁有一個完整的函數式（靜態）網站。

在 _build 目錄內，現在應該有兩個目錄：doctrees 和 HTML。我們對於這個存儲了文檔網站所需的全部文件的 HTML 目錄很感興趣。使用瀏覽器打開 index.html 文件，就會發現如 圖 1 所示的內容。

圖 1. 靜態 HTML 形式的主頁

雖然信息很少，但 Sphinx 能夠創建很多內容。我們擁有一個基本布局，該布局包含有關項目文檔、搜索部分、內容表、附帶名稱和日期的版權聲明、頁碼的一些信息。

搜索部分非常有趣，因為 Sphinx 已經為所有文件建立索引，並使用 JavaScript 的一些強大功能創建了一個可搜索的靜態網站。

還記得我們已將 example 作為一個單獨的文件添加至 清單 6 的 toctree 中的文檔嗎？您可以看到，主標題顯示為內容索引中的主要項目符號，副標題顯示為二級項目符號。Sphinx 小心維護著讓整個結構保持正確。

如果一開始就沒有成功…：進行一些修改後，只需再次運行 make 命令，即可生成這些文件。

所有的鏈接都指向文檔中的正確位置，並且標題和副標題均有定位點，允許直接進行鏈接。比如，Subject Subtitle 部分在瀏覽器中有一個類似 ../example.html#subject-subtitle 的定位點。如前所述，該工具消除了我們對這些瑣碎的、重複的需求的顧慮。

圖 2 顯示了 example.rst 如何顯示為靜態網站中的 HTML 文件。

圖2. HTML 頁面示例

添加圖形

簡明的段落、圖像和圖形都為項目文檔增加趣味性和可讀性。Sphinx 有助於利用這些有可能添加了靜態文件的主要元素來吸引讀者的注意。

添加靜態文件的正確語法很容易記憶。只要將靜態文件放置 _static 目錄（Sphinx 在創建文檔布局時創建了該目錄）中，就可以輕鬆地對其進行引用。在 清單 9，查看 reStructuredTex 文件中的引用應該是什麼樣子的。在本例中，我將其添加在 example.rst 的底部。

清單 9. example.rst 的靜態清單

.. image:: _static/system_activity.jpg

生成文檔之後，應將圖像正確放置在我們為有關係統活動的 JPEG 小圖像指定的地方。它看上起應該類似於 圖 3。

圖 3. 系統活動圖像

結束語

本文介紹了開始使用 Sphinx 的一些基礎知識，但仍有許多內容有待我們探索。Sphinx 能夠用不同的格式導出文檔，但要求安裝額外的庫和軟體。可生成的格式包括：PDF、epub、man (UNIX Manual Pages) 和 LaTeX。

對於複雜的圖形，有一個插件可將 Graphviz 圖形添加至您的文檔項目。我曾經不得不為一個小型辦公網路地圖創建一個插件，但它表現相當出色，無需使用其他工具，便可在同一文檔中獲取所有的東西。與 Graphviz 插件類似，有大量可用於 Sphinx 的插件（亦稱為擴展）。Sphinx 提供了一些插件，比如 interSphinx，該插件允許您鏈接不同的 Sphinx 項目。

如果生成的輸出的外觀不符合您的喜好，Sphinx 還提供了許多主題，可應用它們來完全改變 HTML 文件呈現文檔的方式。一些重要的開源項目，如 Celery 和 Lettuce，通過更改 CSS 並擴展模板完全更改了 HTML 的外觀。請參閱 參考資料 部分，以獲取這些項目的鏈接、解釋如何擴展的文檔的鏈接以及修改默認 CSS 和布局的鏈接。

Sphinx 改變了我對編寫文檔的看法。從一開始的毫無靈感，到現在能夠輕易編製我的幾乎所有的個人開源項目以及少數內部項目，我感到非常興奮。使用 Sphinx 可輕鬆檢索遺忘在您自己文檔中的信息。

下載資源

本文的樣例 Sphinx 項目 (example_sphinx_project.zip | 142KB)

相關主題

• 
  

  Sphinx 項目文檔



• 
  

  Sphinx 擴展：查找第三方擴展的完整列表和一些外部引用。



• 
  

  Theming and Templating：瀏覽解釋擴展當前主題和應用新主題的部分。



• 
  

  Celery 項目文檔 使用 Sphinx 修改 CSS 和 Font 的默認值。



• 
  

  Python Programming Language 文檔：構建 Sphinx 是為了支持 Python 上的完整文檔。



• 
  

  Lettuce 是另一個開源項目，它（極大地）修改了 Sphinx 生成 HTML 的方式。



• 
  

  Pacha: System Configuration Engine 是我使用 Sphinx 實現的開源項目之一。



• 
  

  developerWorks 中國網站開源技術專區：獲取大量 how-to 信息、工具和項目更新，以幫助您了解如何使用開源技術進行開發，以及如何同 IBM 產品相結合使用。



• 
  

  Twitter 上的 developerWorks：關注我們最新的新聞。



• 
  

  隨時關注 developerWorks 技術活動和網路廣播。



• 
  

  訪問 developerWorks Open source 專區獲得豐富的 how-to 信息、工具和項目更新以及最受歡迎的文章和教程，幫助您用開放源碼技術進行開發，並將它們與 IBM 產品結合使用。

看完本文有收穫？請轉

發分享給更多人

關注「P

ython開發者」，提升Python技能

喜歡這篇文章嗎？立刻分享出去讓更多人知道吧！

本站內容充實豐富，博大精深，小編精選每日熱門資訊，隨時更新，點擊「搶先收到最新資訊」瀏覽吧！

請您繼續閱讀更多來自 Python開發者 的精彩文章: