For the ones who don't know the Dash.app - it's an excellent offline API documentation browser for macOS, with documentation sets for 200+ APIs, 100+ cheat sheets and the ability to build your own docset for your favorite language / framework / pet project.

We gonna use the lastly mentioned feature to create a 3rd party docset for the Crystal programming language with the help of dashing CLI tool, and that's the trip I invite You for.

Once upon a time there was (and still is, as well as many others) a SiteSucker, a website downloader tool, which could be used to fetch a website for offline usage, like the Crystal API docs in this case.

But, in the age of rampant automation, from CI to AI, why should we bother ourselves with the tedious, manual dance of picking, clicking, waiting, and spending our valuable time, on a process that could easily be automated - i.e. turned into sth, like a GitHub Actions workflow paired with good ol' wget?

Let's enter crystal-dash-docset - Crystal.docset documentation generator ⚙️

The workflow_dispatch event

Since the standard events are not gonna be a big use for us (unless doing nightly builds, which I won't be covering in this post), we'll use a dedicated event for manual builds: workflow_dispatch.

That lil' fella allows triggering a workflow manually, with (optional) inputs.

on:
  workflow_dispatch:
    inputs:
      crystalVersion:
        description: "Crystal version"
        required: true

The Process

• We use macos-latest out of laziness since it makes installing dashing a simple brew install matter
• We set CRYSTAL_VERSION environment variable - needed by the download.sh script - to the value of the given crystalVersion input
• Installing dependencies is done through brew bundle (via Brewfile which, similarly to the known-from-ruby-world Gemfile, describes dependencies for the project), in our case only wget and dashing
• download.sh bash script is responsible for fetching the /reference/ along with /api/{CRYSTAL_VERSION}/ docs
• build.sh does the final job of building the Crystal.docset out just downloaded docs

jobs:
  build:
    name: Build dockset for Crystal version ${{ github.event.inputs.crystalVersion }}
    runs-on: macos-latest
    env:
      CRYSTAL_VERSION: ${{ github.event.inputs.crystalVersion }}

    steps:
      - name: Download source
        uses: actions/checkout@v2

      - name: Install dependencies
        run: brew bundle

      - name: Download docs
        run: ./download.sh

      - name: Build docset
        run: ./build.sh

Artifacts

Once the Crystal.docset is built, it's uploaded - via actions/upload-artifact@v2 - as an (compressed) artifact.

Release

As the last step, the release with the freshly built docset is created through softprops/action-gh-release@v1.

Et voilà 🎉

Finally, you can consume the fruits of CI's labor by downloading one of the releases and adding it into your Dash.app (macOS) or Zeal (Linux, Windows).