add option to force template .Dir be the path of a local module

[peczenyj]

how it works

If we define a list of local packages (format path like in the output of go list -f '{{ .Dir }}' ./...) and use the output as template {{ .Dir }}/README.md we can use one single command execution to generate the docs for all packages.

Unfortunately, on versioned modules, it does not understand the package name + version (v1, v2 ...) and it generates wrong documentation.

the workaround is to add a comment in the package like

package foo // import "gitlab.nereides.weborama.com/go/my-project/v666/foo"

However this requires a massive rewrite on all source code and... it is kinda ugly

A better solution seems to list the packages as remote packages ( like using go list ./...), however if we do this, the .Dir attribute will be hard coded . and all files will be generated as the current README.md (last wins)

by adding an new option --force-local-dir we:

1. open the go.mod file and parse the content
2. use the package name to find the relative path to the package
3. profit

IF we want to avoid parse the go.mod file, we can specify the full package name with version like this, using the new option --full-package-name:

$ go list ./...|xargs /usr/bin/time -p ../../../github.com/Weborama/gomarkdoc/bin/gomarkdoc --force-relative-urls --output "{{ .Dir }}/README.md" --force-local-dir --full-package-name gitlab.nereides.weborama.com/go/wdx2-libs/v5
...

testing on project wdx2-libs:

using current go.mk

• running make docs

$ time -p make docs
...
==== Creating/updating gitlab.nereides.weborama.com/go/wdx2-libs/v5/wqueue/README.md
/home/tiago/work/go/bin/gomarkdoc --force-relative-urls --output=/home/tiago/work/go/src/gitlab.nereides.weborama.com/go/wdx2-libs/wqueue/README.md gitlab.nereides.weborama.com/go/wdx2-libs/v5/wqueue
real 30,58
user 76,79
sys 24,69

• running make docs_check

$ time -p make docs_check
...
==== Checking gitlab.nereides.weborama.com/go/wdx2-libs/v5/wqueue/README.md
/home/tiago/work/go/bin/gomarkdoc --force-relative-urls --check --output=/home/tiago/work/go/src/gitlab.nereides.weborama.com/go/wdx2-libs/wqueue/README.md gitlab.nereides.weborama.com/go/wdx2-libs/v5/wqueue
real 30,51
user 78,09
sys 24,89

using current go.mk with option -j to run in parallel

• running make docs

$ time -p make -j docs
...
==== Creating/updating gitlab.nereides.weborama.com/go/wdx2-libs/v5/wqueue/README.md
/home/tiago/work/go/bin/gomarkdoc --force-relative-urls --output=/home/tiago/work/go/src/gitlab.nereides.weborama.com/go/wdx2-libs/wqueue/README.md gitlab.nereides.weborama.com/go/wdx2-libs/v5/wqueue
real 20,21
user 73,95
sys 25,75

• running make docs_check

$ time -p make -j docs_docs
...
==== Checking gitlab.nereides.weborama.com/go/wdx2-libs/v5/wqueue/README.md
/home/tiago/work/go/bin/gomarkdoc --force-relative-urls --check --output=/home/tiago/work/go/src/gitlab.nereides.weborama.com/go/wdx2-libs/wqueue/README.md gitlab.nereides.weborama.com/go/wdx2-libs/v5/wqueue
real 17,86
user 63,35
sys 22,50

new command line tool

• generate docs (like make docs)

$ go list ./...|xargs /usr/bin/time -p ../../../github.com/Weborama/gomarkdoc/bin/gomarkdoc --force-relative-urls --output "{{ .Dir }}/README.md" --force-local-dir -vv
...
DEBUG found default branch devel for remote [email protected]:go/wdx2-libs.git dir=./wqueue
DEBUG resolved repository with remote https://gitlab.nereides.weborama.com/go/wdx2-libs, default branch devel, path from root / dir=./wqueue
real 13.39
user 36.07
sys 11.18

• check if docs are ok (like make docks_check)

$ go list ./...|xargs /usr/bin/time -p ../../../github.com/Weborama/gomarkdoc/bin/gomarkdoc --force-relative-urls --output "{{ .Dir }}/README.md" --force-local-dir -vv -c
...
DEBUG found default branch devel for remote [email protected]:go/wdx2-libs.git dir=./wqueue
DEBUG resolved repository with remote https://gitlab.nereides.weborama.com/go/wdx2-libs, default branch devel, path from root / dir=./wqueue
real 14.20
user 39.76
sys 11.71

it means

1. with the new option is pretty fast generate or verify the documentation
2. since it is a new option, the program is backward compatible