资讯专栏INFORMATION COLUMN

Dash助手: 任意html转换为Docset

Michael_Lin / 1617人阅读

摘要:在使用之前,我将的文档镜像到本地,以便随时使用。当我遇见之后,我常常想如果能将我离线的文档转换为格式,丢给管理,那该多美妙。

原文地址

作为一名程序员,最离不开的就是文档了,大多数情况下我们都是通过文档了解一个陌生的领域。想象一下,打开了一堆文档,在文档中跳来跳去,多么的不优雅!所以Bogdan Popescu一怒之下开发了dash,解放了太多在文档中跳来跳去的码农。

dash主要有以下特点:

自带大量常用文档(iOS/Mac/PHP/Python/Java等)

支持用户自定义文档(scrapy/requests/beautifulsoup等)

快速搜索文档及 API

管理和搜索代码片段

无缝插入众多第三方应用(Alfred/Xcode/Terminal等)

dash界面左侧列出所有的文档,支持标签页和书签功能,在搜索框内通过输入关键字,可以查找相关的API、文档,并且响应速度非常快!下面先来一睹Dash芳容吧:

虽说dash官方给了足够多的Docset文档,不过有时候仍然不够用,这时候我们可以去找第三方的Docset,如果找不到,那么只好自己动手丰衣足食啦。

其生成DocSets帮助文档中,有许多种生成Docset的方法介绍,比如从AppleDoc(Objective-C Source Files)、Python(Sphinx or PyDoctor)
、Javadoc、Any HTML Documentation生成文档等。注意,这里可以从Any HTML Documentation生成Docset文档,真是大福利!

html2Dash

相信大家都很喜欢python的requests吧,它的语法以及文档十分简单明了,不愧它HTTP for Humans的称号。在使用Dash之前,我将requests的文档镜像到本地,以便随时使用。其实,我不只离线了requests的文档,还有beautifulsoup4、scrapy等许多文档。我甚至将酷壳整个站点都离线了下来,以便拜读人家的文章。

当我遇见Dash之后,我常常想如果能将我离线的文档转换为Docset格式,丢给Dash管理,那该多美妙。幸好,dash官网提供了html文件转换为DocSet的方法,整个转换主要有以下几个步骤:

创建Docset目录结构(Create the Docset Folder);

复制HTML文件(Copy the HTML Documentation);

创建Info.plist文件(Create the Info.plist File);

创建SQLite数据库文件(Create the SQLite Index);

写入SQLite数据索引(Populate the SQLite Index);

为了将转换的过程自动化,我写了一个小程序html2dashhtml2dash放在github上,使用十分简单,可以用./html2dash.py -h查看帮助,如下:

$ /html2dash.py -h
usage: html2dash.py [-h] [-n NAME] [-d PATH] [-i FILENAME] [-p INDEX_PAGE]
                    SOURCE

positional arguments:
  SOURCE                Directory containing the HTML documents

optional arguments:
  -h, --help            show this help message and exit
  -n NAME, --name NAME  Name the docset explicitly
  -d PATH, --destination PATH
                        Put the resulting docset into PATH
  -i FILENAME, --icon FILENAME
                        Add PNG icon FILENAME to docset
  -p INDEX_PAGE, --index-page INDEX_PAGE
                        Set the file that is shown

下面是转换requests文档的示例:

$ ./html2dash.py -n requests -i ~/Documents/requests-sidebar.png ~/Documents/requests  
Create the Docset Folder!  
Copy the HTML Documentation!  
Create the SQLite Index    
Create the Info.plist File  
Create the Icon for the Docset!  
Generate Docset Successfully!  

效果如下:

从HTML制作的文档其实不算真正意义上的“文档”,因为并没有Classes、Functions、Types等API,如下图:

下面介绍一下我常用的镜像站点的方法。

镜像站点

镜像站点最简单的方法就是使用wget,一般像这样使用:

wget -r -p -k -np http://tengine.taobao.org/book/ 

关于wget的更多内容,可以看之前的一篇文章:如何使用wget

其实OS X 下有一款比较不错的工具可以用来镜像站点,那就是SiteSucker。比如要下载requests的文档,只需要输入文档首页地址,然后设置Path Constraint为Directory即可下载文档,如下图:

前面两种镜像方法都不是很完美,因为有时候某些站点(比如Scrapy)引用的css、js文件来自其他的站点,这时候如果选择只镜像当前目录下面的文件,就会漏掉这些资源文件,目前还没有找到一个合适的方法解决这个问题。

参考:
Dash-Docset-Creator
Generate a docset from any HTML Documentation

文章版权归作者所有,未经允许请勿转载,若此文章存在违规行为,您可以联系管理员删除。

转载请注明本文地址:https://www.ucloud.cn/yun/37424.html

相关文章

  • Markdown编辑器

    摘要:当你完成了一篇文章的写作在上方工具栏找到文章导出,生成一个文件或者文件进行本地保存。导入如果你想加载一篇你写过的文件或者文件,在上方工具栏可以选择导入功能进行对应扩展名的文件导入,继续你的创作。 @TOC 欢迎使用Markdown编辑器 你好! 这是你第一次使用 Markdown编辑器 所展示的欢迎页。如果你想学习如何使用Markdown编辑器, 可以仔细阅读这篇文章,了解一下Mark...

    mykurisu 评论0 收藏0
  • Underscore和Lo-Dash中的Collections _.each

    摘要:遍历集合,对集合中的每个元素执行回调。因此,上面的判断等价于是预先定义的空对象,内部用于提前结束循环的标志,并没有对外公开。 _.each 遍历集合,对集合中的每个元素执行回调。 API Lo-Dash _.forEach(collection [, callback=identity, thisArg]) Aliases each Arguments collection (Arr...

    weakish 评论0 收藏0
  • [译] HTML5 媒体源扩展(MSE):把影视制作级别的视频格式带入 Web

    摘要:还有一个值得关注的是加密媒体扩展标准其支持用原生和开发播放加密视频。专业流媒体发布商将无法依靠微软的技术在和安卓设备上的火狐来加密自己的内容。因此,不同的系统组合,如用于和安卓的,用于和的,还有用于的。 英文原文:HTML5 Media Source Extensions: Bringing Production Video To The Web 在过去的十几年,像Flash和Silv...

    Allen 评论0 收藏0

发表评论

0条评论

最新活动
阅读需要支付1元查看
<