Dash文档制作教程
前言
什么是Dash
- 面向程序员的文档库(Mac)
- 代码片段管理工具
这是强烈推荐给每天在各种API文档中摸爬滚打的程序员们的神器。
为什么要自己制作文档
- 官方的源中没有相关文档
- 文档在离线下体验更好
最近在研究 Phantomjs ,相关的文档比较缺乏,主要是看官网的教程及API等,遇到一个问题就是家里的网络访问国外的站点太慢,体验太差。可能是因为技术较新的原因,发现Dash中并没有相关文档,给Dash作者反馈后,得到了如下的答复:
I've recorded your vote towards a PhantomJS docset. Currently, this docset has 11 votes. Please note that I don't generate docsets unless more users ask for them.
You can, however, generate your own docsets by following the instructions at http://kapeli.com/docsets.
呵呵,看来只有自己动手,丰衣足食了。
制作教程
前提
- Mac系统;需要安装 python 环境,第三方库 bs4
- 原始的文档在网站上(官网上所谓的
7. Any HTML Documentation
),例如本例 http://phantomjs.org/
生成站点镜像
cd ~ && wget -m http://phantomjs.org/
本例中使用 wget 的 --mirror(-m) 选项建立一个镜像站点,会把站点的各层目录、文件(图片、样式、html等)保存到本地,这些文件就是要导入到Dash的最原始的文件。
文本处理
经过上一步建立到本地的镜像文件里面很可能使用的是绝对路径(例如<a href="http://phantomjs.org/release-names.html"
),想要离线索引,就必须先转换成相对路径(注意不同的层级关系),建议先进行简单的分析,然后用脚本进行批处理。
这一步是比较重要的一步,会影响到文档的质量,如果处理不好很可能某些链接由于路径不对而看不了。
例如我根据不同的目录层级关系,对html里面的域名进行不同层级的替换:
for dir in `ls -d ~/phantomjs.org/api/*/`; do
sed -i 's/http:..phantomjs.org/..\/..\//g' $dir/*.html;
for sub in `ls -d $dir*/`; do
sed -i 's/http:..phantomjs.org/..\/..\/..\//g' $sub*.html;
done
done
拷贝文档
Dash要求相求文档文件要放在 *.docset 目录下,可以按照默认的目录层级:
mkdir -p Phantomjs.docset/Contents/Resources/Documents/
mv ~/phantomjs.org/* Phantomjs.docset/Contents/Resources/Documents/
创建Info.plist文件
里面可以定义一些配置信息,例如是否允许Js等
touch Phantomjs.docset/Contents/Info.plist
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>CFBundleIdentifier</key>
<string>Phantomjs</string>
<key>CFBundleName</key>
<string>Phantomjs</string>
<key>DocSetPlatformFamily</key>
<string>Phantomjs</string>
<key>isDashDocset</key>
<true/>
</dict>
</plist>
生成索引
- 先创建一个SQLite数据库文件,并生成一张表。
sqlite3 Phantomjs.docset/Contents/Resources/docSet.dsidx
CREATE TABLE searchIndex(id INTEGER PRIMARY KEY, name TEXT, type TEXT, path TEXT);
.exit
- 用 python 脚本填充索引
这一步也是比较重要的一步,也是最复杂的一步。数据库文件的索引对应Dash文档的目录(或者索引),质量高的索引可以表达出很丰富层级关系以及分类,例如函数、类、熟悉、模块、分类、条目、命令等。
简单起见,这里只填充了官网首页的4个‘分类’(Category),使用 python 实现,具体如何填充需要根据文档实际情况调整脚本:
#!/usr/local/bin/python
import os, re, sqlite3
from bs4 import BeautifulSoup, NavigableString, Tag
db = sqlite3.connect('Phantomjs.docset/Contents/Resources/docSet.dsidx')
cur = db.cursor()
try:
cur.execute('DROP TABLE searchIndex;')
except:
pass
cur.execute('CREATE TABLE searchIndex(id INTEGER PRIMARY KEY, name TEXT, type TEXT, path TEXT);')
cur.execute('CREATE UNIQUE INDEX anchor ON searchIndex (name, type, path);')
docpath = 'Phantomjs.docset/Contents/Resources/Documents'
page = open(os.path.join(docpath,'index.html')).read()
soup = BeautifulSoup(page)
any = re.compile('^[a-z]{3,20}$|documentation.html|faq.html')
for tag in soup.find_all('a', {'href':any}):
name = tag.text.strip()
if len(name) > 0:
path = tag.attrs['href'].strip()
if path.split('#')[0] not in ('index.html', 'index.htm', 'bookindex.html'):
cur.execute('INSERT OR IGNORE INTO searchIndex(name, type, path) VALUES (?,?,?)', (name, 'Category', path))
print 'name: %s, path: %s' % (name, path)
db.commit()
db.close()
添加icon及其他注释说明等
制作一个 logo 后(从官网logo截一张大图),导出两种尺寸,16x16、 32x32
touch Phantomjs.docset/icon.png
touch Phantomjs.docset/icon@2x.png
此时,双击Phantomjs.docset即可导入到 Dash 中了,还可以在偏好设置里面刷新文档内容,如果有修改 logo 需要先删除文档再添加进来。
共享到社区(github)
通过互联网贡献一点自己的努力吧。
- fork 项目 https://github.com/Kapeli/Dash-User-Contributions
- 按照里面的要求把自己的文件上传上去,然后就可以 pull request 了
参考
该文只是记录了自己在制作文档过程中的基本思路,请大家一定仔细参考官网的教程:
Dash文档制作教程的更多相关文章
- Struts2 API的chm格式帮助文档制作教程
Struts2 API的chm格式帮助文档制作教程 在SSH三个框架中,Struts2的API文档是最难做的,这里所说的格式是chm格式的,chm的格式很方便,Hibernate API文档和Spri ...
- 传智播客C/C++各种开发环境搭建视频工具文档免费教程
传智播客作为中国IT培训的领军品牌,一直把握技术趋势,给大家带来最新的技术分享!传智播客C/C++主流开发环境免费分享视频文档中,就有写一个helloworld程序的示范.火速前来下载吧 所谓&quo ...
- help文档制作 chm
程序中的help文档制作 所用工具:HTML Help Workshop 文件包括:各个html文档,帮助页面的具体内容 hhc文档:help的目录文件 hhk文档:help的索引文件 MAP文件夹中 ...
- .net core的Swagger接口文档使用教程(二):NSwag
上一篇介绍了Swashbuckle ,地址:.net core的Swagger接口文档使用教程(一):Swashbuckle 讲的东西还挺多,怎奈微软还推荐了一个NSwag,那就继续写吧! 但是和Sw ...
- ABBYY PDF Transformer+从文件选项中创建PDF文档的教程
可使用OCR文字识别软件ABBYY PDF Transformer+从Microsoft Word.Microsoft Excel.Microsoft PowerPoint.HTML.RTF.Micr ...
- 强大的矢量图形库:Raphael JS 中文帮助文档及教程
Raphael 是一个用于在网页中绘制矢量图形的 Javascript 库.它使用 SVG W3C 推荐标准和 VML 作为创建图形的基础,你可以通过 JavaScript 操作 DOM 来轻松创建出 ...
- https://github.com/coolnameismy/BabyBluetooth github上的一个ios 蓝牙4.0的库并带文档和教程
The easiest way to use Bluetooth (BLE )in ios,even bady can use. 简单易用的蓝牙库,基于CoreBluetooth的封装,并兼容ios和 ...
- chm开源文档制作
作为开发人员,API文档是非常关键的^_^,但是很多时候官方提供的文档是html的docs,不方便于携带查询,本章主要介绍chm文档的制作方法. 使用jd2chm制作chm文档 安装之前必须先安装 h ...
- .Net程序帮助文档制作
一,准备工作 1,首先介绍一款VS的代码注释插件GhostDoc 你也许认为我们在代码中敲入///就能自动生成xml注释,但这种注释是没有说明文字的.而GhostDoc可以生成一些简单的说明文字,如果 ...
随机推荐
- Arduino uno 引脚说明
http://openhome.cc/Gossip/Books/mBlockArduino1-3and1-4.html http://swf.com.tw/?p=406
- D3中selection之使用
1. 极为重要的reference: [1] How selections works. http://bost.ocks.org/mike/selection/ [2] Nested selecti ...
- WebGL入门教程(五)-webgl纹理
前面文章: WebGL入门教程(一)-初识webgl WebGL入门教程(二)-webgl绘制三角形 WebGL入门教程(三)-webgl动画 WebGL入门教程(四)-webgl颜色 这里就需要用到 ...
- shell处理输入
1.在运行脚本时指定参数,直接在脚本名称后边跟随需要添加的参数,在运行的过程中,$0代表程序名,$1代表第一个参数,$2代表第二个参数,一直到第九个,从第十个参数开始需要变成${10}等,即需要添加花 ...
- SQL 语句与性能之联合查询和联合分类查询
select * from t1 left join t2 on t2.sysno =t1.ASysNo left join t3 on t3.sysno =t2.ASysNo left join t ...
- iOS路径沙盒文件管理(转载)
iOS路径沙盒文件管理,看到博主总结的很好,转载过来,原文:http://www.aichengxu.com/view/35264 一.iOS中的沙盒机制 iOS应用程序只能对自己创建的文件系统读取文 ...
- System中记录体函数命名怪异
//1019unit System; 中发现记录体函数命名怪异//乍一看,很怪异,其实是结构体里面 的变量后面直接写 函数类型了.不像传统先定义T***Event = procedure(S ...
- Angular内置指令(二)
目录: $rootScope,ng-app,.run(),ng-include,ng-repeat,ng-if,ng-switch,ng-init ng-show/ng-hide,ng-model,n ...
- css3之3D魔方动画(小白版)
在这里分享一下3D魔方动画,html5+CSS3即可完成~无图无真相,先上效果图 第一步非常简单,就是先将魔方的结构画出来.大家都玩过魔方,知道魔方是一个有六个面的正方体.这里我们先写一个大的di ...
- linux 用户管理
linux 用户管理 创建一个用户 foo 这个用户只能在/home/foo 上面增加删除文件, foo 不能在其他目录加减文件 useradd -d /home/foo -m foo [root@] ...