DIV CSS 佈局教程網

您现在的位置: DIV+CSS佈局教程網 >> 網頁腳本 >  >> HTML基礎知識 >> HTML5詳解
Sphinx 快速上手:從 sphinx-quickstart 到中文輸出設定
編輯:HTML5詳解     

Sphinx 這名字有點容易誤會——本文談的不是那個全文搜尋引擎,而是 Python 社群用來把 reStructuredText 原始檔轉成網站或 PDF 的「文件生成工具」。寫過 Python 官方文件的人應該都看過它的成品樣子。

一、建立文件專案

先切換到你想放文件的位置,例如 /home/wwwroot/doc:

cd /home/wwwroot/doc

接著啟動精靈:

sphinx-quickstart

程式會逐步詢問一些選項,絕大部分直接按 Enter 使用預設值即可。幾個值得留意的問題:

Enter the root path for documentation.
> Root path for the documentation [.]:

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/N) [n]: y

> Name prefix for templates and static dir [_]:

> Project name: F2E Cookbook
> Author name(s): imbingdian

> Source file suffix [.rst]: .txt

三個建議:選擇分離 source 與 build 目錄(輸入 y),後續管理清楚得多;專案名稱與作者會出現在產出文件的各處,認真填;文件副檔名預設是 .rst,若團隊習慣用 .txt 就在這裡改。
之後的問題一路 Enter 就好。

完成後,doc 目錄下會多出這些內容:

build/      # 產出的文件放這裡
source/     # 原始檔與 conf.py 設定檔
make.bat
Makefile

試著產生 HTML:

make html

到 build 目錄底下看看,HTML 已經生成好了。

二、簡易設定

所有設定都集中在 source/conf.py。

1)把介面語言改成中文

找到這行並取消註解:

#language = None
language = 'zh_CN'

其他常見語言代碼:

bn – Bengali        ca – Catalan       cs – Czech         da – Danish
de – German         en – English       es – Spanish       fi – Finnish
fr – French         hr – Croatian      it – Italian       ja – Japanese
lt – Lithuanian     nl – Dutch         pl – Polish        pt_BR – Brazilian Portuguese
ru – Russian        sl – Slovenian     tr – Turkish       uk_UA – Ukrainian
zh_CN – Simplified Chinese              zh_TW – Traditional Chinese

2)更換主題

找到 html_theme = 'default',把 default 換成想要的名稱即可。官方內建主題清單見:
sphinx.pocoo.org/theming.html

3)其他常用選項

html_title          # 瀏覽器分頁與頁首顯示的標題
html_static_path    # 放自訂 CSS、圖片的目錄
extensions          # 需要啟用的擴充,例如 autodoc、todo、graphviz
latex_documents     # 輸出 PDF 時的版型設定

改完設定後,重新執行一次 make html 就會生效。若還需要 PDF,加上 make latexpdf(需先安裝 LaTeX 環境)即可。更細節的設定項目建議直接查閱官方文件,那裡的說明最完整也最新。

XML學習教程| jQuery入門知識| AJAX入門| Dreamweaver教程| Fireworks入門知識| SEO技巧| SEO優化集錦|
Copyright © DIV+CSS佈局教程網 All Rights Reserved