The webapp devdocs.io is an excellent browser for API documentations. It is the web equivalent to Dash, a native app available only on macOS that probably inspired the creation of devdocs.

While dugging into some web extensions, I found the need to look at some API documentation. Unfortunately, they were available only on developer.google.com and developer.mozilla.org, both of which lacked a pleasant searching experience. So, I thought I'd add their documents to devdocs.

Devdocs has a public repository on Github, which contains plenty of good information about contributing to the project. It is indicated there that adding new docs requires a bit of development effort, therefore setting up a dev environment for the webapp will be needed.

Setting up devdocs

Devdocs requires:

  • Ruby 2.4.0
  • libcurl
  • Javascript runtime

Ruby's website, ruby-lang.org, mentions RubyInstaller as a way to install Ruby on Windows. Unfortunately, rubyinstaller.org doesn't appear to offer Ruby 2.4.0 yet.

Instead, I thought I'd use the new Linux on Windows feature to install Ruby. There's an helpful guide just for that on gorails.com, which I used to write the guide below.

Guide

This guide assumes you've already enabled Bash on Ubuntu on Windows. If you haven't done that already and need help, then follow the first steps in the guide I linked previously.

# Install Ruby dependencies
# -------------------
sudo apt-get update  
sudo apt-get install git-core curl zlib1g-dev build-essential libssl-dev libreadline-dev libyaml-dev libsqlite3-dev sqlite3 libxml2-dev libxslt1-dev libcurl4-openssl-dev python-software-properties libffi-dev


# Install rbenv
# -------------------
# This is a ruby version manager.
# It handles having multiple versions of Ruby for dev purposes.
# -------------------
git clone https://github.com/rbenv/rbenv.git ~/.rbenv  
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc  
echo 'eval "$(rbenv init -)"' >> ~/.bashrc  
exec $SHELL

git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build  
echo 'export PATH="$HOME/.rbenv/plugins/ruby-build/bin:$PATH"' >> ~/.bashrc  
exec $SHELL


# Install Ruby 2.4.0
# -------------------
# I read that the installation process includes the compilation of Ruby.
# On my XPS laptop, this took a while (maybe 10+ minutes?).
# -------------------
rbenv install 2.4.0  
rbenv global 2.4.0  
ruby -v


# Install gems
# -------------------
# 1. bundler
# 2. rack
# 3. thor
# -------------------
gem install bundler  
gem install rack -v 1.6.5

# Setup devdocs
# -------------------
# 1. Clone devdocs
# 2. Install devdocs
# 3. Download default documentations.
# 4. Start devdocs
# -------------------
git clone https://github.com/Thibaut/devdocs.git  
cd devdocs  
bundle install  
bundle exec thor docs:download --default  
bundle exec rackup

# Note:
# In the devdocs' README, the author didn't specify
# "bundle exec" before the thor and rackup commands.
# See why here: 
# https://robots.thoughtbot.com/but-i-dont-want-to-bundle-exec

Firewall

On my system, I had to open the port 9292 in Windows' firewall, otherwise devdocs wouldn't run well. I did this by creating an outbound port rule.

Note on filesystems

If you followed my guide step by step, you installed devdocs on the WSL filesystem. It'll work there, but you won't be able to edit those files with Windows applications.

To work around this, you can copy the devdocs directory somewhere on your C: drive, such as C:\Users\user\projects\devdocs\.

The catch, then, is that some documents use forbidden (on Windows) characters in their filenames. That means that you might encounter a lot of missing pages if you decide to copy devdocs on C: and run it from there. However, I've find that it otherwise works well enough.

Note on performance

Running the devdocs application seems pretty demanding for my system. The Task Manager consistently shows the Ruby process as using 30% of the CPU. Maybe this whole thing wasn't such a good idea. I might try installing Linux on another partition instead.

Add new documents

To continue...