Doc-hunt track changes occuring in a source code to help keeping documentation up to date.
How it works ?
Example : README.md
This repository contains a
README.md and it rely heavily on features made in
cmd module (cmd folder in this repository), so to keep file
README.md up to date, we need to track some files in
cmd folder. You can check this repository to have an example how it works with travis.
Part 1 : Setup
To setup this tracking we do :
doc-hunt add config README.md 'cmd/(config.*|update|version|check)(?<!_test).go'
It creates a file
.doc-hunt at the root of this repository and we record it to version control system, this file will track every changes occuring in files recorded in config.
Part 2 : Tracking changes
After few changes in source code, we want to check if we have to update
README.md, we run :
And we get :
---- README.md Updated => cmd/check.go ----
Part 3 : Update doc-hunt
We check if we made changes in file
cmd/check.go that could be documented in
README.md. When everything looks fine, we update
.doc-hunt file doing (we are going to commit
.doc-hunt afterwards) :
From release page download the binary according to your system architecture.
You can pull a docker container from dockerhub, run this command from you root path application :
docker run -it --rm -v $PWD:/app/ antham/doc-hunt config list
if you need a different binary version add it as tag like so :
docker run -it --rm -v $PWD:/app/ antham/doc-hunt:2.1.1 config list
doc-hunt keep a track of version app used to record configuration, it's necessary to use a binary with same major version or configuration needs to be redo to update to a new major version.
Ensure your documentation is up to date Usage: doc-hunt [command] Available Commands: check Check if documentation update could be needed config List, add or delete configuration update Update documentation references version App version Flags: -h, --help help for doc-hunt Use "doc-hunt [command] --help" for more information about a command.
A config line is made with a document (a file, a folder in current repository or an external URL) with one or several sources (a pcre regexp matching file sources that need to be tracked).
Add a new configuration on all php files in two different folders :
doc-hunt config add README.md folder1/.*.php,folder2/.*.php
Add a new configuration on all php files in a folder and exclude test files :
doc-hunt config add README.md 'folder1/.*(?<!_test).php'
-n flag, try config
It's possible to simulate what this command will do adding a
-n option like so :
doc-hunt config add -n README.md folder1/.*.php
List all existing configurations :
doc-hunt config list
Remove unwanted configuration (This command will launch a prompt) :
doc-hunt config del
To check all changes occuring in a source code :
-e flag, crash when a change occurs
doc-hunt crashes when changes are detected (useful in a CI), add a
e flag like so :
doc-hunt check -e
To record every changes and make
doc-hunt not complaining anymore :
New version of
.doc-hunt must be committed with all changes added.