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.