使用Sphinx生成HTML文件的方法

使用Sphinx生成HTML文件的方法

適用環境

• Python 3.6
• Sphinx 1.5.5
• pip
• Windows 7

安裝Sphinx

pip install sphinx

安裝結巴分詞

pip install jieba

安裝sphinx中文搜索插件

從

https://raw.githubusercontent.com/bosbyj/sphinx.search.zh_CN/master/zh_CN.py

下載文件，保存到目錄

C:\Python27\Lib\site-packages\sphinx\search

修改search/__init__.py，在languages中加入

'zh_CN': 'sphinx.search.zh_CN.SearchChinese',

設置語言

在conf.py中加入

language = 'zh_CN'

生成文檔

初始化文檔工程目錄

sphinx-quickstart

編寫配置

略

生成文檔

sphinx-build -b html <SOURCEDIR> <BUILDDIR>

生成index.rst

index.rst用於生成index.html。爲了簡化index.rst文件的編寫，我寫了一個程序，搜索目錄下的rst文件，生成index.rst。

// irg.go
// 遍歷目錄，生成index.rst文件。
// 2017年04月29日

package main

import (
     "flag"
     "fmt"
     "io/ioutil"
     "os"
     "path/filepath"
     "strings"
)

func main() {

     var rootPath string
     var outputFilename string
     flag.StringVar(&rootPath, "path", ".", "note path")
     flag.StringVar(&outputFilename, "output", "index.rst", "output file")
     flag.Parse()

     // map[directory]filename
     fileList := make(map[string][]string)

     filepath.Walk(rootPath, func(filename string, info os.FileInfo, err error) error {
             if err != nil {
                     return nil
             }

             if !info.Mode().IsRegular() {
                     return nil
             }

             if filename == "index.rst" {
                     return nil
             }

             if !strings.HasSuffix(filename, ".rst") {
                     return nil
             }

             directory := "未分類"
             parts := strings.Split(filename, string(os.PathSeparator))
             if len(parts) > 1 {
                     directory = parts[0]
             }

             list, ok := fileList[directory]
             if !ok {
                     list = make([]string, 0)
             }
             list = append(list, strings.Replace(filename, "\\", "/", -1))
             fileList[directory] = list

             return nil
     })

     tocText := ""
     for dir, files := range fileList {
             filenameList := ""
             for _, filename := range files {
                     filenameList += fmt.Sprintf("   %s\n", filename)
             }

             tocText += fmt.Sprintf(tocTreeText, dir, filenameList)
     }

     text := fmt.Sprintf(indexRstText, tocText)
     ioutil.WriteFile(outputFilename, []byte(text), os.ModePerm)
}

var (
     tocTreeText = `
.. toctree::
   :maxdepth: 2
   :caption: %s
   :titlesonly:

%s

`

     indexRstText = `筆記
================================

.. toctree::
   :maxdepth: 2
   :caption: 內容

%s

指引
==================

* :ref:` + "`genindex`\n" +
             "* :ref:`modindex`\n" +
             "* :ref:`search`"
)

參考資料

1. http://sphinxsearch.com/docs/current.html
2. http://www.sphinx-doc.org/en/stable/install.html
3. http://www.jianshu.com/p/d99f1b399ddc
4. https://github.com/bosbyj/sphinx.search.zh_CN

修訂記錄

1. 2017年04月24日 創建文檔。
2. 2017年06月17日 改成rst格式。
3. 2017年06月18日 增長irg代碼。