自己动手制作MySQL Internals Manual For Dash文档

老实说，我刚用Dash没几天，感觉还不错，毕竟有份本地化文档还是比较方便，不用总实时打开MySQL官档网页。不过，目前Dash只有MySQL 5.5 ~ 8.0的官档，没有其他相关文档，有时候想查看Internals Manual或Release Notes就没那么方便了，于是就萌生了自己动手制作Dash文档的念头。

1. 准备工作

1.1 下载MySQL文档

用wget批量、自动下载Internals Manual及MySQL 8.0 Release Notes文档。

[root@yejr.me]# cd /data/mysql-docs

[root@yejr.me]# wget -r -p -np -k --no-check-certificat "https://dev.mysql.com/doc/internals/en/index.html"

[root@yejr.me]# wget -r -p -np -k --no-check-certificat "https://dev.mysql.com/doc/relnotes/mysql/8.0/en/"

[root@yejr.me]# ls -l dev.mysql.com
drwxr-xr-x 3 root root 16Feb2913:25 internals
drwxr-xr-x 3 root root 19Feb2922:19 relnotes

1.2 构建Python环境

制作Dash docset文档，需要用到Python的beautifulsoup4模块，因此要先安装上。安装beautifulsoup4模块挺简单的，用Python的pip就可以了，如果不知道的话，可以先自行搜索一番。

[root@yejr.me]# pip install beautifulsoup4

此外，还需要sqlite数据库，如果没有的话，也先自行安装，用yum就可以了，也挺方便的。

2. 构建Dash docset环境

2.1 创建docset目录结构，复制文件

[root@yejr.me]# cd /data/mysql-docs/dev.mysql.com/doc/internals/

# 以MySQL Internal Manual文档为例，先创建下面的目录
[root@yejr.me]# mkdir -p MySQL_Internal.docset/Contents/Resources/Documents/

# 复制所有文件到docset目录下
[root@yejr.me]# cp en/* MySQL_Internal.docset/Contents/Resources/Documents/

2.2 编辑Info.plist文件

接下来就是要编辑Info.plist文件了，这也是docset的metadata文件了，存储基本信息，以及定义一些配置等。

[root@yejr.me]# cat MySQL_Internal.docset/Contents/Info.plist



    
"1.0" encoding="UTF-8"?>
/span>"-//Apple//DTD PLIST 1.0//EN""http://www.apple.com/DTDs/PropertyList-1.0.dtd">
"1.0">
CFBundleIdentifier
MySQLInternalManualstring>
CFBundleName
MySQLInternalManualstring>
DocSetPlatformFamily
MySQLInternalManualstring>



    
dashIndexFilePath
index.htmlstring>
isDashDocset
<true/>

2.3 生成docset文档索引

Dash的文档索引采用SQLite数据库，SQLite是一个很小巧的、开源的关系型数据库，据说很可能是使用量最大的关系数据库。

先创建docset索引表：

[root@yejr.me]# sqlite3 MySQL_Internal.docset/Contents/Resources/docSet.dsidx
SQLite version 3.28.02019-04-1514:49:49



    
Enter".help"for usage hints.
sqlite> CREATE TABLE searchIndex(id INTEGER PRIMARY KEY, name TEXT, type TEXT, path TEXT);
sqlite> .exit
[root@yejr.me]#

然后用一个Python脚本解析所有文档页面文件，并且生成索引记录，写入到 docSet.dsidx 索引文件中。

这步的工作比较重要，因为后面我们阅读文档时，可能会搜索一些关键词，因此需要尽可能把这些关键词都写到索引文件里。

写入时，各个关键词可以分属不同的类型，常见文档中的类型几乎都支持，像Category、Class、Command、Constant、Function、Interface、Keyword、Module、Namespace等，不一一列举了。

我为了图省事，写入索引时，全部都指定为Keyword了，重点是能搜索到这些关键词就好。

脚本蓝本：https://github.com/drbraden/pgdash/blob/master/pgdoc2set.py

先看下解析文档的Python脚本：

[root@yejr.me]# cat dsidx.py
#!/usr/local/bin/python3

import os, re, sqlite3, sys
from bs4 importBeautifulSoup, NavigableString, Tag

try:



    
# 指定sqlite数据文件
    db = sqlite3.connect('MySQL_Internal.docset/Contents/Resources/docSet.dsidx')
    cur = db.cursor()
except:
print("Open sidx file failed, exit.")
exit

docpath = 'MySQL_Internal.docset/Contents/Resources/Documents'

# 接收参数，便于逐个解析每个文件
doc = "%s"% sys.argv[1];
page = open(os.path.join(docpath, doc)).read()
soup = BeautifulSoup(page, features="html.parser")

any = re.compile('.*')



    
for tag in soup.find_all('a', {'href':any}):
# 删除空格及换行
    name = tag.text.strip()
    name = name.replace("\n","")
if len(name) > 0:
        path = tag.attrs['href'].strip()
if path.split('#')[0] notin('index.html', 'index.htm', 'bookindex.html'):
# 插入索引记录
            sql='INSERT OR IGNORE INTO searchIndex(name,type,path) VALUES ("%s","KEYWORD","%s");'%(name,path);



    
            cur.execute(sql)
# 最后一次性批量提交
db.commit()
db.close()

接下来，我们只需逐个解析文档文件即可：

# 扫描文档目录
for f in`ls en`
do
/usr/local/bin/python3 ./docset.py $f
done

最后发现共写入了5600多条记录。

到这里，一个简陋的Dash文档就制作完成了，快和小伙伴们一起分享下成果吧。

P.S，github上已有很多小伙伴在分享他们的成果了：Kapeli/Dash-User-Contributions（https://github.com/Kapeli/Dash-User-Contributions）。

另外，想要图省事直接获取文档的话，后台发送“dash”关键字获取下载链接，因为Oracle MySQL不让非官方途径发布官网文档，所以不方便直接放上来。之前在我网站下载几个文档并放在上面，也加了入口链接，只是为了方便自己阅读，就这样也被要求下线。

本文参考

Dash文档制作教程，https://www.cnblogs.com/xiangzi888/p/4034808.html
Docset Generation Guide，https://kapeli.com/docsets

知数堂精品课程《Python运维自动化》课程已经在腾讯课堂开播，本课程从零开始，一步一步由浅入深学习Python的运维自动化开发，即便是零基础的同学也可以加入学习，对DBA工程师、运维工程师、在校生及其他有志从事人工智能、大数据开发相关领域的同学都非常有帮助。

下面是报名小程序码，肯定大家推荐给需要的小伙伴们。

下面是本课程的主要内容目录

开课课程规划设计
字符串与正则(2月22日 10:35-11:30)
文件操作与系统管理
配置文件与日志
Python网络编程
Python系统监控
数据库连接与操作
分布式异步消息cerely
常见中间件
面向测试开发
网络主机嗅探
通过ssh管理主机
Ansible搭建与管理
搭建第一个Django应用
Django MVC介绍
Django Cookie与Session
Django使用模块
Django和Vue前后端分离系统
MySQL慢SQL分析平台
前端页面设计
课程总结

手机QQ扫码入群向助教咨询

点“在看”给我一朵小黄花