小白的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
好了，最初的文章index.rst如下。注意toctree下一定要空一行，否则不行。
1 地缘看世界 2 ====================================== 3 4 .. toctree:: 5 6 前言/前言1 7 前言/前言2 8 前言/前言3 9 前言/前言4 10 前言/前言5 11 12 search 13 ====================================== 14 * :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查看到如下设置：
1 # maps language name to module.class or directly a class 2 languages = { 3 'da': 'sphinx.search.da.SearchDanish', 4 'de': 'sphinx.search.de.SearchGerman', 5 'en': SearchEnglish, 'xxx':engine19 'zh': 'sphinx.search.zh.SearchChinese', 20 # 'zh_CN': 'sphinx.search.zh.SearchChinese', 21 } # type: Dict[str, Any]
字典的前面是语言，后面是搜索用的模块。conf.py里面的language = 'zh'就是根据这个文件来判断用哪个语言的搜索模块，注意：要完全一致的名字，最开始按照说明设置的language = 'zh-CN'是不行的。
然后查看zh.py发现如下代码，意识到是因为没装JIEBA模块，所以搜索不行。JIEBA是个中文分词的程序，了解了一下，搜索还得依靠分词。
1 def init(self, options: Dict) -> None: 2 if JIEBA: 3 dict_path = options.get('dict') 4 if dict_path and os.path.isfile(dict_path): 5 jieba.load_userdict(dict_path) 6 7 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
