stefanwalther/verb repository overview

⁠docker-verb

⁠Table of Contents

⁠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:

1. Install nodemon⁠

$ npm install -g nodemon

1. 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"
  },

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

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

1. 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:

1. First of all I use husky⁠ to be able to add git hooks (precommit, prepublish, etc.)
2. 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

⁠Installation

⁠Prerequisites

• Docker for Mac⁠ / Docker for Windows⁠

⁠Known Issues

... none known so far ...

⁠Changelog

See CHANGELOG file⁠

⁠About

⁠Author

Stefan Walther

• stefanwalther.io⁠
• qliksite.io⁠
• qlikblog.at⁠
• github/stefanwalther⁠
• twitter/waltherstefan⁠
• LinkedIn⁠

⁠Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue⁠. The process for contributing is outlined below:

1. Create a fork of the project
2. Work on whatever bug or feature you wish
3. Create a pull request (PR)

I cannot guarantee that I will merge all PRs but I will evaluate them all.

⁠License

Copyright © 2021, Stefan Walther.

MIT