使用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`"
)

参考资料

http://sphinxsearch.com/docs/current.html

http://www.sphinx-doc.org/en/stable/install.html

http://www.jianshu.com/p/d99f1b399ddc

https://github.com/bosbyj/sphinx.search.zh_CN

修订记录

2017年04月24日 建立文档。

2017年06月17日 改为rst格式。

2017年06月18日 增加irg代码。