Every coder will say so: when learning a new language or using a new toolkit or library, a great documentation makes the difference. It is however usually really boring to browse when it comes as a pdf, or in html format.
Documentation engines, including doxygen, qdoc, appledoc among many great others, provide indexation and allow their authors to generate databases for fast queries of symbols. This is where IDEs come, as the documentation lookup becomes part of the code writing experience.
They however present many disadvantages: they are usually bound to a language and a small set of libraries. Also, they hide many aspects of the development life cycle: managing dependencies, hiding linking and post build phases. I won’t argue on why these are drawbacks, but ail those reasons make me use a single editor for all languages I’m coding with, all tools I’m using in a development cycle: Emacs.
I’ve been using macs for many years now, but I happen to hack on other operating systems as well. There is one software that made me love coding on the mac: Dash. It is an API documentation browser that pops up with a key sequence and disappears when it looses focus. It hosts and downloads more than 130 famous docsets and provide very fast searching and a nice browsing experience. Also, its author, Bogdan Popescu is a very nice person, easy to talk with and is very open when it comes to contributing to Dash, see this post.
Helm is an emacs incremental completion and selection narrowing framework, a fork of the well known anything.el, that is currently very popular for many developers are using it as a frontend for their own packages.
Here comes Helm-Dash, a wonderful emacs packages, available on Melpa that uses Dash docsets inside emacs to browse documentation. Note that is does not require the Dash app, and so, works on any platform, just as Emacs !
The installation is quite straight forward, you’ll need to install
sqlite, then either clone the repository to get
or use MELPA with
M-x package-install helm-dash.
helm-dash-install-docset will display a list of available docsets,
once downloaded, activate it using
then start a query using
I’ll focus on my setup, which deviates from Helm-Dash’s intended use, as I want my docsets to be retrieved whenever I clone my Prelude. Note that the author were very reactive when I filled these issues.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81
This setup defines some helper functions:
jwintz/dash-path (docset)provides the installation path for a docset
jwintz/dash-install (docset)installs a docset only if it is not already installed, i.e. if the path returned by the previous function does not exists
jwintz/dash-hook*sets some shortcuts to use dash
By default, Helm-Dash uses emacs’
browse-url builtin to display
the queried token documentation in your default browser. For me, it
then launches Safari every-time I look up one definition. However, I
like to stay within Emacs, so it minimizes my keystrokes and does not
force me to use the mouse.
There are many web browsers for Emacs, I will cite two of them:
eww is the newcomer that is EmacsLisp only,and is probably gonna
be the way to go any time soon, I have however chosen
even if it requires the installation of a third party binary, namely
brew install does the job just fine).
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
There you go !