A Knitting Weekend with Dash and Python

For the last few months, I’ve become a huge fan of the quiet weekend, the weekend when no plan is the plan, and you are in no hurry at all. I woke up on Saturday morning, and I decided that this weekend was going to be a quiet one. After watching a late morning football game from the English Premier League – yup, I refuse to call it soccer 😀 – I decided to write some code-nothing big, just a few lines of codes to improve my experience with Dash, a tool that I’ve been using for a few months.

Dash is a MacOS application that offers offline documentation for hundreds of programming languages, frameworks and libraries. Dash is awesome for offline programming when using spotty WiFi or on long-haul flights. While it is free as in beer, it’s one of the programs that are worth paying for.

The Problem

I’ve been using Dash for quite some time and have been really satisfied with the preset selection of documentation sets. At some point, I started running into scenarios when I was using libraries/packages whose documentations aren’t available for Dash. So, my objective was to generate documentation sets for these libraries myself. I should point out that I mostly work with Python packages, and most Python packages use sphinx as their main framework for building documentation. So, my goal was to find a way to easily build documentation sets and integrate them with Dash.

The Solution: Doc2dash and Sphinx To The Rescue

After few minutes of google searches, I found doc2dash. doc2dash is a great tool for converting HTML documentation to Dash’s format. doc2dash takes the output of Sphinx documentation and converts it to a Dash documentation package.

Show Me The Code!

In Just a few steps, I was able to build a docset for Zarr using dash2doc:

  • Create new conda environment and install dependencies

    $ conda create -n dash-docs -c conda-forge \
         doc2dash sphinx-rtd-theme numpydoc sphinx-issues
    $ conda activate dash-docs
  • Pull down the project form GitHub and build the documentation

    $ git clone https://github.com/zarr-developers/zarr-python.git
    $ cd zarr-python
    $ python -m pip install -e .
    $ cd docs
    $ make html
  • Finally, run doc2dash with a few commands

    $ doc2dash --name zarr --index-page index.html --enable-js \
      --add-to-dash _build/html

    And with that I had a shiny new Zarr docset in Dash:

    Once I was confident that I understood how to do this for one project, I decided to automate this process for a bunch of other projects. By dinner time (on Saturday) I felt like I was on the right track. After a few more hours on Sunday and Monday, I had a GitHub repository with continuous integration via CircleCI up and running, and had a dozen docsets generated:

Was It Worth Fifteen or Twenty Hours of My Life?

I think so: I took pleasure in doing something that I knew how to do and in creating something that would fit my needs perfectly.

Sitting in a chair in front a computer screen while listening to MIX 100 Denver Radio station 😀, I was reminded of the intriguing parallels between knitting and programming:

“Knitting is Coding, and Yarn is a Programmable material.”

On quiet weekends like this I write code for fun, and Visual Studio Code & Python are my yarn and needles.