Quick access to local offline reference docs through handy key-binding

Introduction

Premise

Through a simple key-binding (shift+ctrl+d) I can quickly launch or focus reference documentation (using devdocs).

Quick open reference docs after pressing a key-binding

Steps

So, how are we going to do this?

  1. Weโ€™re going to install some software to facilitate the mechanics: wmctrl, nativefier and devdocs
  2. Weโ€™re going to write a bash script that launches or focuses the devdocs
  3. Weโ€™re going to bind the bash script to a key-binding

(nb: This guide was tested on Ubuntu 18.04)

Installing software

๐Ÿ›ƒ Installing wmctrl (1 of 3)

Whatโ€™s wmctrl and why do we need it?

1
$ man wmctrl
2
NAME
3
   wmctrl - interact with a EWMH/NetWM > compatible X Window Manager.
4
DESCRIPTION
5
   wmctrl  is  a  command that can be used to interact with an X Window manager that is compatible with the EWMH/NetWM specification.  wmctrl can query the window manager for information, and it can request that certain window management actions be taken.

Weโ€™ll use wmctrl to check if our API reference application is running, and focus on it. If itโ€™s not running, weโ€™ll start it. wmctrl is easily installed on Ubuntu through the package manager:

bash
1
# Installs wmctrl
2
sudo apt install wmctrl

๐Ÿ’ก Installing nativefier (2 of 3)

Nativefier is a tool to make a native wrapper for any web page. Weโ€™ll use it to get a local version of DevDocs installed, in case weโ€™re ever without Wi-fi.

Itโ€™s quite easy to install, just run the following npm command to install it as a global dependency:

bash
1
# Install nativefier globally
2
npm install nativefier -g

๐Ÿ“– Installing devdocs (3 of 3)

This is the actual documentation tool weโ€™ll be using. You can insert your own if you like.

Weโ€™ll use nativefier to install a local version of DevDocs:

bash
1
# Create software folder
2
mkdir ~/Software && cd ~/Software
3
4
# Generate local electron version of devdocs
5
nativefier --name "DevDocs" "https://devdocs.io/"

We also want to have a .desktop file installed, so we can launch the application and save it in our favorites sidebar:

bash
1
echo "[Desktop Entry]" \
2
   "Type=Application" \
3
   "Terminal=false" \
4
   "Exec=/home/<your-username>/Software/dev-docs-linux-x64/dev-docs" \
5
   "Name=DevDocs" > \
6
   "# Icon=/path-to-optional-icon.png" \
7
   > ~/.local/share/applications/devdocs.desktop

(If youโ€™re having an issue with adding the application to your favorites in a later stage, add the following to this file: StartupWMClass=dev-docs-nativefier-49fe5b. Where dev-docs-nativefier-49fe5b is the name you see when you hover over the running app icon in your application bar).

Action time

๐Ÿš€ Implementing the launch script

bash
1
# Create a folder to store our script
2
mkdir ~/bin
3
4
# Create launch/focus script
5
echo "#!/bin/bash" \
6
   (wmctrl -l | grep -q DevDocs) && wmctrl -a DevDocs || gtk-launch devdocs" \
7
   > `~/bin/devdocs.sh`
8
9
# Make the script executable for the user
10
chmod u+x ~/bin/devdocs.sh

What exactly does this script do? Letโ€™s break it down:

  • (wmctrl -l | grep -q DevDocs): List all applications and find DevDocs
  • wmctrl -a DevDocs: If found, focus on application DevDocs
  • gtk-launch devdocs if not found, launch application devdocs

โŒจ๏ธ Adding key-binding

Adding the key-binding is easy in Ubuntu, go to Settings -> Keyboard and hit the + icon to add a new key-binding:

Quickly configure key-binding

๐ŸŽ‡ Thatโ€™s it!

Test your key-binding by hitting shift+ctrl+d (or your chosen binding). The devdocs application should launch, and if itโ€™s already running it should focus when using the key-binding.

If you want to run all of the above commands in one go, use the following gist:

bash
1
bash <(curl -s https://gist.githubusercontent.com/flipflopsandrice/07d84567f4197ef253055066669078b3/raw/6976125db4d5b7b22ba69e5ed3206be223f1ea68/install-devdocs.sh)