Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/stefanwalther/docker-verb
Run verb by using a docker-container.
https://github.com/stefanwalther/docker-verb
docker docker-image readme verb verbose
Last synced: about 2 months ago
JSON representation
Run verb by using a docker-container.
- Host: GitHub
- URL: https://github.com/stefanwalther/docker-verb
- Owner: stefanwalther
- License: other
- Created: 2017-05-05T23:05:59.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2022-06-01T14:06:08.000Z (over 2 years ago)
- Last Synced: 2023-03-30T12:04:29.168Z (over 1 year ago)
- Topics: docker, docker-image, readme, verb, verbose
- Language: Dockerfile
- Size: 67.4 KB
- Stars: 6
- Watchers: 0
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.yml
- Contributing: docs/contributing.md
- License: LICENSE.md
Awesome Lists containing this project
README
# docker-verb
> Run verb on Docker.
## Table of Contents
- [Motivation](#motivation)
- [Run](#run)
- [Configuration](#configuration)
- [Recipes](#recipes)
* [Watching doc changes](#watching-doc-changes)
* [Run only if necessary](#run-only-if-necessary)
- [Installation](#installation)
* [Prerequisites](#prerequisites)
- [Known Issues](#known-issues)
- [Changelog](#changelog)
- [About](#about)
* [Author](#author)
* [Contributing](#contributing)
* [License](#license)
_(TOC generated by [verb](https://github.com/verbose/verb) using [markdown-toc](https://github.com/jonschlinkert/markdown-toc))_
## Motivation
[verb](https://github.com/verbose/verb) is a great solution to document projects, create README files, enter [README driven development](https://www.google.de/search?q=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
```sh
$ 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
```json
{
"name": "Your Repo",
"scripts": {
"docs": "docker run --rm -v ${PWD}:/opt/verb stefanwalther/verb"
}
}
```
Then, whenever you want to generate your docs, run:
```sh
$ 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](https://nodemon.io/)
```bash
$ npm install -g nodemon
```
2) Add a watch script to your package.json
```bash
"scripts": {
"docs": "docker run --rm -v ${PWD}:/opt/verb stefanwalther/verb",
"docs:watch": "nodemon --config ./nodemon.json --exec 'yarn' docs"
},
```
3) Add a nodemon.json config file to your root dir:
```json
{
"ext": "md",
"verbose": false,
"ignore": [
"README.md"
],
"watch": [
".verb.md",
"docs"
]
}
```
4) Run docs:watch
```bash
$ 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](https://github.com/typicode/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:_
```sh
"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:_
```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](https://docs.docker.com/docker-for-mac/) / [Docker for Windows](https://docs.docker.com/docker-for-windows/)
## Known Issues
... none known so far ...
## Changelog
See [CHANGELOG file](CHANGELOG.yml)
## About
### Author
**Stefan Walther**
* [github/stefanwalther](https://github.com/stefanwalther)
* [twitter/waltherstefan](http://twitter.com/waltherstefan)
* [LinkedIn](https://www.linkedin.com/in/stefanwalther/)
### Contributing
Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](https://github.com/stefanwalther/docker-verb/issues). 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