Sphinx 使用手冊

引言

?  譯者前言   ::   Contents   ::   Sphinx初嘗  ?

引言

該文檔是Sphinx建立文檔的參考. Sphinx 將 reStructuredText 源文件集轉換為豐富的輸出格式,并自動產生參考文獻、索引等. 簡言之,如果你有一個包含reST-格式的文檔的目錄(包含文檔的所有文件或子目錄), Sphinx 會生成組織合理的HTML文件(在另一個目錄里),使得瀏覽及導航功能使用非常方便. 通用一份源文件,你可以生成LaTeX 文件,然后編譯成 PDF 版本的文檔, 也可以直接使用 rst2pdf 生成PDF 文件.

重點討論的是手寫文檔而不是自動生成的API文檔. 但是我們對于兩種都支持的很好,甚至支持兩種內容混合的文檔, 假如你需要純凈的API文檔,查看 Epydoc, 它可以解析 reST.

不同文檔系統的轉換

這一節搜集了一些有用的提示,幫助我們從其他的文檔系統遷移到reStructuredText/Sphinx.

  • Gerard Flanagan (人名)寫了一個腳本把純凈的HTML轉換為 reST文本; 你可以到 Python 索引頁 查看.
  • 原來的Python文檔轉換為 Sphinx, 代碼托管在 the Python SVN repository. 它包含將Python-doc-style LaTeX 標記轉換為Sphinx reST 的生成代碼.
  • Marcin Wojdyr 寫了一個腳本,將 Docbook 轉換為 reST ; 可查看 Google Code.
  • Christophe de Vienne 寫了一個將 Open/LibreOffice 文檔轉換為 Sphinx的工具: odt2sphinx.
  • 轉換不同的標記語言, Pandoc 也是一個非常有用的工具.

在其他系統中使用

請參考 pertinent section in the FAQ list.

前提

Sphinx 運行前需要安裝 Python 2.4 或者 Python 3.1 , 以及 docutilsJinja2 庫. Sphinx 必須工作在 0.7 版本及一些 SVN 快照(不能損壞). 如果需要源碼支持高亮顯示,則必須安裝 Pygments 庫.

如果使用 Python 2.4 ,還需要 uuid.

用法

更深入的話題,請參考 Sphinx初嘗 .

?  譯者前言   ::   Contents   ::   Sphinx初嘗  ?

四川快乐12开奖时间