Sphinx 正體中文搜尋的擴充套件

網路搜尋的資料都要修改 Sphinx 的程式碼，對用 pip 作套件管理的系統並不好。 參考 Sphinx 的擴充套件教學後，就基於 bosbyj/sphinx.search.zh_CN 加入了一些例外處理和從設定檔自訂字典檔的功能，做了正體中文的擴充套件 sphinx.ext.search.zh_TW 也提交給 Sphinx，不知道會不會 marge 到未來版本。

安裝結巴中文分詞

$ pip install jieba

安裝正體中文的擴充套件

$ git clone https://github.com/enhao/sphinx.ext.search.zh_TW.git _extension

修改專案目錄下的 conf.py

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
sys.path.insert(0, os.path.abspath('_extension'))

...

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['search-zh_TW']

...

# Language to be used for generating the HTML full-text search index.
# Sphinx supports the following languages:
#   'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
#   'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr'
html_search_language = 'zh_TW'

# A dictionary with options for the search language support, empty by default.
# Now only 'ja' uses this config value
html_search_options = {'dict': '_extension/dict/zh.dict'}

sphinx.ext.search.zh_TW 的字典檔是用結巴中文分詞的 dict.txt.big ，不設定 html_search_options 的話，會使用結巴中文分詞的預設字典

參考

• GitHub - bosbyj/sphinx.search.zh_CN
• 用Python做科學計算 - 關於本書的編寫
• GitHub - fxsjy/jieba
• 如何使用 JIEBA 結巴中文分詞程式
• Sphinx - Tutorial: Writing a simple extension

Sphinx 的中文搜尋

最簡單的方式就是直接用日文分詞演算法

修改專案目錄下的 conf.py

...

# Language to be used for generating the HTML full-text search index.
# Sphinx supports the following languages:
#   'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
#   'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr'
html_search_language = 'ja'

# A dictionary with options for the search language support, empty by default.
# Now only 'ja' uses this config value
html_search_options = {'type': 'default'}

參考

• 用 reStructuredText 寫網站與書

Sphinx 匯出 HTML 到指定路徑

Sphinx 匯出 HTML 的預設路徑在專案目錄下的 _build/html

  $ make html
  $ ls _build
  doctrees html

而在 _build 下會產生快取的目錄 doctrees

匯出到指定路徑只要在專案目錄下執行

  $ sphinx-build -d _build/doctrees . /usr/local/nginx/html

其中 -d 是指定快取的目錄，/usr/local/nginx/html 是匯出的目錄

Sphinx 匯出中文 PDF

安裝 MacTeX

修改專案目錄下的 conf.py

...

language = 'zh_TW'

...

latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
'papersize': 'a4paper',

# The font size ('10pt', '11pt' or '12pt').
#'pointsize': '10pt',

'classoptions': ',english',
'inputenc': '',
'utf8extra': '',

# Additional stuff for the LaTeX preamble.
'preamble': '''
\usepackage{xeCJK}
\setCJKmainfont[BoldFont=Heiti TC, ItalicFont=STKaiti]{Heiti TC}  % 設定中日韓字型
\setCJKmonofont[Scale=0.8]{Courier New}  % 設定中日韓等寬字型
\XeTeXlinebreaklocale "zh"  % 設定斷行演算法為中文
\XeTeXlinebreakskip = 0pt plus 1pt  % 設定中文字距與英文字距
''',

# Latex figure (float) alignment
#'figure_align': 'htbp',
}

字型可以參考網頁中英文字型(font-family)跨平台設定最佳化或檢視系統已安裝的字型

  $fc-list :lang=zh-tw

匯出 PDF

  $ make latex
  $ cd _build/latex
  $ xelatex *.tex

參考

• 用Python做科學計算 - 關於本書的編寫
• Mac下的Latex中文解決方案: XeTeX
• 網頁中英文字型(font-family)跨平台設定最佳化

修改 Sphinx 的佈景主題

幾個不錯的佈景主題

Read the Docs Sphinx Theme

安裝

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

Sphinx Bootstrap Theme

安裝

  $ pip install sphinx_bootstrap_theme

修改專案目錄下的 conf.py

import sphinx_bootstrap_theme

...

html_theme = "sphinx_bootstrap_theme"
html_theme_path = [sphinx_bootstrap_theme.get_html_theme_path()]

Solar Theme

安裝

  $ pip install solar-theme

修改專案目錄下的 conf.py

import solar

...

html_theme = "solar"
html_theme_path = [solar.get_html_theme_path()]

使用 Sphinx 製作文件

安裝 Sphinx

  $ pip install sphinx

指定專案名稱、作者、版本，使用 EPUB 來建立文件專案

  $ sphinx-quickstart -q -p example -a author -v 1.0.0 --epub docs

或以互動的方式，回答問題來建立

  $ sphinx-quickstart docs

建完會產生一個專案目錄

  $ tree docs
  docs
  ├── Makefile
  ├── _build
  ├── _static
  ├── _templates
  ├── conf.py
  ├── index.rst
  └── make.bat

  3 directories, 4 files

直接編輯 index.rst 就可以開始撰寫文件了，語法可以參考 A ReStructuredText Primer

執行

  $ make html
  $ make singlehtml
  $ make epub
  $ make latexpdf

分別匯出 HTML、EPUB 和 PDF 在 _build 目錄底下，匯出 PDF 要先安裝 MacTeX

參考

• Sphinx
• A ReStructuredText Primer