docker-verb

July 2, 2021 · View on GitHub

Run verb on Docker.

Motivation
Run
Configuration
Recipes
- Watching doc changes
- Run only if necessary
Installation
- Prerequisites
Known Issues
Changelog
About

(TOC generated by verb using markdown-toc)

Motivation

verb is a great solution to document projects, create README files, enter README driven development. This project helps to make it even easier to use by "dockerizing" verb.

(By using this solution you do not need to install verb as a global node.js package anymore)

Run

$ docker run --rm -v ${PWD}:/opt/verb stefanwalther/verb

What does actually happen here?

A docker container using the given solution will be spinned up
-v mounts the current directory to the docker container
Finally, after the container has been built, verb will be executed (and the container being destroyed)

Configuration

I recommend to add a task into your package.json file, which triggers the creation of your README.md file

{
  "name": "Your Repo",
  "scripts": {
    "docs": "docker run --rm -v ${PWD}:/opt/verb stefanwalther/verb"
  }
}

Then, whenever you want to generate your docs, run:

$ npm run docs

Recipes

Some recipes I have come up over time, using verb nearly on a daily basis.

Watching doc changes

If you want to auto-build your docs whenever you make changes, there is a pretty neat way to achieve that:

Install nodemon

$ npm install -g nodemon

Add a watch script to your package.json

"scripts": {
    "docs": "docker run --rm -v ${PWD}:/opt/verb stefanwalther/verb",
    "docs:watch": "nodemon --config ./nodemon.json --exec 'yarn' docs"
  },

Add a nodemon.json config file to your root dir:

{
  "ext": "md",
  "verbose": false,
  "ignore": [
    "README.md"
  ],
  "watch": [
    ".verb.md",
    "docs"
  ]
}

Run docs:watch

$ npm run docs:watch

If you are not making any changes to either .verb or any document in ./docs, then your README.md will be re-generated.

Run only if necessary

If you commit often, you don't want to miss when to run verb, but on the other hand I don't want to run it if not necessary. This is how I manged to achieve this goal:

First of all I use husky to be able to add git hooks (precommit, prepublish, etc.)
I combine a prepush hook with a custom script which just figures out if running verb is necessary (in this case only if there are changes in the .verb file or if anything has changed in the ./docs/ directory).

package.json:

  "scripts": {
    "docs-if-necessary": "./scripts/docs-if-necessary.sh",
    "docs": "docker run --rm -v ${PWD}:/opt/verb stefanwalther/verb",
    "prepublish": "npm run docs-if-necessary"
  }

./scripts/docs-if-necessary.sh:

#!/usr/bin/env bash

if (git status | grep -E "docs/|.verb.md" -q);
then
  npm run docs;
  
  # Stop the push
  # Note: Instead of exiting you could even go one step further and 
  # automatically git commit the newly created README.md. I have
  # experimented with that, but didn't really like it.
  exit 10; 
  
fi