小白的linux笔记11：放弃gitbook，转战Sphinx

gitbook生成的html目录不折叠且链接失效

装好了gitbook和nodejs，本以为可以安心的做电子书了。

谁想到gitbook慢的一P，而且导出来的html目录不折叠，最关键的是链接有问题，用不了，无语。

目录折叠可以用一个插件toggle-chapters。或者用这个作者的方法。https://blog.csdn.net/u014651560/article/details/86488117

而链接用不了，很少有记录有人处理过这个问题。这里有一个可以用，但是要每次都处理，而且他的目录居然是每次点击都要刷新加载，太慢了，不符合潮流啊。https://blog.csdn.net/yageeart/article/details/87868631

降级后编译有问题，所以又找到了另一个方案：修改编译后的theme.js：

vim _book/gitbook/theme.js
1
把其中 if(m)for(n.handler 替换成 if(false)for(n.handler ，但是重新编译后还是会覆盖，从 .gitbook/versions/3.2.3/node_modules/gitbook-plugin-theme-default/src/build.sh 里的

10 # Compile JS
11 browserify src/js/core/index.js | uglifyjs -mc > _assets/website/gitbook.js
12 browserify src/js/theme/index.js | uglifyjs -mc > _assets/website/theme.js
1
2
3
可以看出这里有可能有些端倪，但是没有时间尝试了，后期有时间再修改吧。
————————————————
版权声明：本文为CSDN博主「程序人生禅」的原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接及本声明。
原文链接：https://blog.csdn.net/yageeart/article/details/87868631

没办法，只好转投其他的，比如Sphinx。

安装 Sphinx

基本教程：https://zh-sphinx-doc.readthedocs.io/en/latest/tutorial.html

在虚拟环境中安装吧，sudo virtualenv makebook，然后进入makebook目录，. bin/activate

第一次安装出现问题，仔细阅读error，是pip源的问题，另一次是因为没有用sudo运行。

所以sudo pip install -i https://pypi.tuna.tsinghua.edu.cn/simple sphinx。如果想一劳永逸参考这里：https://blog.csdn.net/lambert310/article/details/52412059

raise ReadTimeoutError(self._pool, None, 'Read timed out.' )
pip._vendor.urllib3.exceptions.ReadTimeoutError: HTTPSConnecti onPool(host='pypi.tuna.tsinghua.edu.cn', port=443): Read timed out.

https://blog.csdn.net/lambert310/article/details/52412059

sphinx-quickstart启动（虚拟环境不行，还得在正常环境）

需要输入名字，作者等基本信息，选择分开source和build，然后会生成source和build两个文件夹，source里面有confi.py是基本设置， index.rst是主页。

sphinx是用 reStructure语言，又得学习新语法，这里有个demo快速可以入门。https://sphinx-demo.readthedocs.io/zh/latest/

https://sphinx-demo.readthedocs.io/zh/latest/_sources/index.rst.txt

https://www.cnblogs.com/seayxu/p/5603876.html

https://longzeping.github.io/2018/08/03/reStructuredText%E5%92%8CMarkdown%E8%AF%A6%E7%BB%86%E5%AE%9E%E7%94%A8%E5%AF%B9%E6%AF%94/

好了，最初的文章index.rst如下。注意toctree下一定要空一行，否则不行。

 地缘看世界

 ======================================

 .. toctree::

    前言/前言1

    前言/前言2

    前言/前言3

    前言/前言4

    前言/前言5

 search

 ======================================

 * :ref:`search`

设置markdown支持

也可以通过设置支持markdown，或再换一个工具mkDocs，mdbook之类。

https://stackoverflow.com/questions/2471804/using-sphinx-with-markdown-instead-of-rst

pip install --upgrade recommonmark
在conf.py中设置
extensions = ['recommonmark']

source_suffix = {
'.rst': 'restructuredtext',
'.txt': 'markdown',
'.md': 'markdown',
}

搜索问题：搜不出结果

试验了一下，明明存在相应的文字，搜索总是搜不出应有的结果。是搜索设置的问题。

参看conf.py设置里面的language和html_search_language的内容。

http://www.sphinx-doc.org/en/stable/usage/configuration.html?highlight=language#confval-language

搜索依靠的是/usr/local/lib64/python3.6/site-packages/sphinx/search下的模块，

打开__init__.py查看到如下设置：

 # maps language name to module.class or directly a class

 languages = {

     'da': 'sphinx.search.da.SearchDanish',

     'de': 'sphinx.search.de.SearchGerman',

     'en': SearchEnglish,

 　　　　'xxx':engine     'zh': 'sphinx.search.zh.SearchChinese',

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

 }  # type: Dict[str, Any]

字典的前面是语言，后面是搜索用的模块。conf.py里面的language = 'zh'就是根据这个文件来判断用哪个语言的搜索模块，注意：要完全一致的名字，最开始按照说明设置的language = 'zh-CN'是不行的。

然后查看zh.py发现如下代码，意识到是因为没装JIEBA模块，所以搜索不行。JIEBA是个中文分词的程序，了解了一下，搜索还得依靠分词。

     def init(self, options: Dict) -> None:

         if JIEBA:

             dict_path = options.get('dict')

             if dict_path and os.path.isfile(dict_path):

                 jieba.load_userdict(dict_path)

         self.stemmer = get_stemmer()

于是安装pip install jieba。再make html发现好很多了。

但是还是按词搜索的逻辑，比如搜索“角度”可以有结果，但搜“角”就不行。原理问题吧，再研究吧。不行就导出pdf再搜索。

开始没有找到钥匙，还是这几个线索帮了我，虽然是几年前的，内容是针对旧版Sphinx的：

http://www.typemylife.com/restructuredtext-sphinx-html-chinese-search/

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

我使用的是Python 3.4 。安装的是 jiaba 分词工具。因为这个工具一直在更新。
安装过程如下
sphinx 安装笔记===============
首先安装好Python—————
-我的环境是win7-64位，安装的是Python 3.4.2
安装Python的sphinx插件———————
-在Python目录下Scripts目录下运行“pip3.4.exe install sphinx”命令。就可以安装sphinx扩展包了。 :: pip3.4.exe install sphinx
解决reStructuredText Sphinx HTML中文搜索—————————————
-安装jieba3k （因为我的是Python3.4）
:: C:Python34Scripts>pip3.4.exe install jieba3k
在https://github.com/bosbyj/sphinx.search.zh_CN下载zh_CN.py
:: https://github.com/bosbyj/sphinx.search.zh_CN
拷贝到C:\Python34\Lib\site-packages\sphinx\search 目录下修改这个目录下的_init_.py文件，找到
:: from sphinx.search import en, ja languages = { ‘en’: en.SearchEnglish, ‘ja’: ja.SearchJapanese, }
修改为
:: from sphinx.search import en, ja, zh_CN languages = { ‘en’: en.SearchEnglish, ‘ja’: ja.SearchJapanese, ‘zh_CN’: zh_CN.SearchChinese }
在 sphinx 工程的 conf.py 中修改
:: language = ‘zh_CN’ html_search_language = `zh_CN` 然后就可以 make html 了为reStructuredText Sphinx扩展侧边栏目录—————————————
在Python目录下Scripts目录下运行“easy_install-3.4.exe sphinxcontrib-fulltoc” 就可以安装这个扩展包了修改Sphinx项目配置文档conf.py 。为扩展参数 extensions = [ ] 添加值 ‘sphinxcontrib.fulltoc’ 记得后面加逗号重新执行一次make html

写好source之后，make html