doc2dash——制作自己的dash文档

Dash是Mac上一款超棒的应用，提供了诸如C/C++/Python甚至是OpenCV/Vim等软件包或工具软件的参考文档。只要使用App的“Download Docsets”功能，就能轻松下载相应文档。使用的时候只需在Dash的搜索框内输入相应关键词，Dash会在所有文档中进行搜索，给出相关内容的列表。点击我们要寻找的条款，就能够直接在本地阅读文档。在Ubuntu/Windows平台上，Dash也有对应的替代品，例如zeal就是一款Windows/Linux平台通用的Dash替代软件。

这样强大的软件，如果只能使用官方提供的文档岂不是有些大材小用？doc2dash就是一款能够自动生成Dash兼容docset文件的工具。例如，可以使用它为PyTorch生成本地化的docset文件，并导入Dash/zeal中，在本地进行搜索阅读。这不是美滋滋？

本文章是基于doc2dash的官方介绍，对其使用进行的总结。

安装doc2dash

doc2dash是基于Python开发的。按照官方网站介绍，为了避免Python包的冲突，最好使用虚拟环境进行安装。我的机器上安装有Anaconda环境，所以首先使用conda create命令新建用于doc2dash的虚拟环境。

1	conda create -n doc2dash

接下来，激活虚拟环境，并使用pip install命令安装。

1 2	source activate doc2dash pip install doc2dash

doc2dash支持的输出格式可以通过sphinx或者pydoctor。其中前者更加常用。下面以PyTorch项目的文档生成为例，介绍doc2dash的具体用法。

生成PyTorch文档

doc2dash使用sphinx生成相应的文档。在上述安装doc2dash的过程中，应该已经安装了sphinx包。不过我们还需要手动安装，以便处理rst文档。

1	pip install sphinx_rtd_theme

进入PyTorch的文档目录docs/，PyTorch已经为我们提供了Makefile，调用sphinx包进行文档处理，可以选择make html命令生成相应的HTML文档，生成的位置为build/html。

1 2	# in directory $PYTORCH/docs, run make html

接下来，就可以使用doc2dash来继续sphinx的工作，生成Dash可用的文档文件了~使用-n指定生成的文件名称，后面跟source文件夹路径即可。

1 2	# $PYTORCH/docs/build/html即为生成的HTML目录 doc2dash -n pytorch $PYTORCH/docs/build/html

之后，把生成的pytorch.docset导入到Dash中即可。如下图所示，点击“+”找到文件添加即可。

在Ubuntu上安装zeal

zeal是Dash在非Mac平台上的替代软件。在Ubuntu上可以使用如下方式轻松安装（见官方网站介绍）。

1
2
3

sudo add-apt-repository ppa:zeal-developers/ppa
sudo apt-get update
sudo apt-get install zeal

安装后，可以使用Tool/Docsets下载相应的公开文档。如果想要添加自己生成的文档，只需要将生成的docset文件放到软件的文档库中即可，默认位置应在$HOME/.local/share/Zeal/Zeal/docsets。