Using older documentation with Dash | The journey that counts

Table of Contents

In note 20230116 I talked about the offline API browser Dash, a MacOS application that lets you download the HTML documentation for various software packages and search it offline. Dash doesn’t download the HTML documentation from the original package location, but from its own sites. Other clients than Dash can download these so-called docsets, but only Dash can download docsets for older versions of a software package. Other clients can only access the most recent build. This note describes how to build the docsets for older versions yourself and install them side-by-side.

Directory https://github.com/Kapeli/feeds lists the XML files that each describe where to download the documentation for one. Take for example Python_3.xml, which starts as follows:

<entry>
    <version>.12.1</version>
    <ios_version>1</ios_version>
    <url>http://sanfrancisco.kapeli.com/feeds/Python_3.tgz</url>
    <url>http://london.kapeli.com/feeds/Python_3.tgz</url>
    <url>http://newyork.kapeli.com/feeds/Python_3.tgz</url>
    <url>http://tokyo.kapeli.com/feeds/Python_3.tgz</url>
    <url>http://frankfurt.kapeli.com/feeds/Python_3.tgz</url>
    <other-versions>
        <version><name>3.12.1</name></version>
        <version><name>3.12.0</name></version>
        <version><name>3.11.6</name></version>
        <version><name>3.11.5</name></version>
        <version><name>3.11.4</name></version>

The XML refers to other versions that are available/known. I googled for their URL but didn’t find much. The Google Group for Zeal, a Linux client for docsets, has this question from August 2015 that asks where you can download older versions. The thread doesn’t give a definite answers, but it does mention Zeal GitHub issue #208 (and to be complete, a broken link to an older ExtJS package). About the issue, it’s unresolved and ends with a question for pointers from June 2023. So it seems that downloading the other, older docsets is not an option for other clients.

Creating and installing docsets for older packages

Fortunately you can build the docsets yourself thanks to the excellent doc2dash utility by Hynek Schlawack. For example, the following small script

downloads the offline documentation for Python 3.9.7 to /tmp and unzips it, and
calls doc2dash to create a docset named Python-3.9.7.

cd /tmp
wget https://docs.python.org/ftp/python/doc/3.9.7/python-3.9.7-docs-html.zip
unzip python-3.9.7-docs-html.zip
doc2dash --name Python-3.9.7 python-3.9.7-docs-html

When successful, these commands end with:

Converting intersphinx docs from '/tmp/python-3.9.7-docs-html' to 'Python-3.9.docset'.
Parsing documentation...
Added 12,915 index entries.
Patching for TOCs... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00

To install it, copy directory /tmp/Python-3.9.docset to ~/.docsets and it should be available to the Dash client of your choice. By the way, note that the name of the docset is Python-3.9.docset, even though I specified the patch version. I don’t know what the rationale for that is - haven’t looked into it yet - but it’s a nitpick.

One word of warning: do not call doc2dash for documentation in your current directory. If you do something like doc2dash --name Python-3.9.7 ., doc2dash will also pick up the new HTML files that it just generated, again and again and again. This will result in really large directory trees…

Enabling docsets in Emacs

In note 20230226 I describe how to configure a specific set of docsets for Python mode in Spacemacs. That approach is still valid but it specifies the same docsets for each Python project. This is not ideal when you use different Python versions for different projects. Fortunately you can also configure project-specific docsets.

dash-docs provides buffer-local variable dash-docs-docsets to list the docsets that should be active for that buffer. If you set that variable as a directory-local variable in a .dir-locals.el, you have your project-specific docsets. For example, in one of my projects I use the following setup:

;;; Directory Local Variables
;;; For more information see (info "(emacs) Directory Variables")

((python-mode . ((dash-docs-docsets . ("Python-3.9" "Pandas-1.3"))))

A more ad-hoc approach is via interactive function helm-dash-activate-docset. Execute it, select the docset you also want to activate and you’re off to go.