From 886de55a93588952eb27ca8caec63e449cfe756f Mon Sep 17 00:00:00 2001 From: docktermj Date: Thu, 11 Jul 2024 17:56:21 -0400 Subject: [PATCH] #71 Update documentations --- .github/coverage/README.md | 18 +++- .github/linters/README.md | 58 +++++++---- .github/workflows/README.md | 186 ++++++++++++++++++++++++++++++------ Makefile | 10 +- README.md | 33 ++++--- docs/development.md | 142 ++++++++++++++------------- docs/examples.md | 2 +- makefiles/darwin.mk | 7 ++ makefiles/linux.mk | 7 ++ makefiles/windows.mk | 9 +- 10 files changed, 342 insertions(+), 130 deletions(-) diff --git a/.github/coverage/README.md b/.github/coverage/README.md index 61408c4..9ca939c 100644 --- a/.github/coverage/README.md +++ b/.github/coverage/README.md @@ -2,7 +2,19 @@ ## testcoverage.yaml +- [testcoverage.yaml] - Used by `coverage:` in - - [go-test-darwin.yaml](../workflows/go-test-darwin.yaml) - - [go-test-linux.yaml](../workflows/go-test-linux.yaml) - - [go-test-windows.yaml](../workflows/go-test-windows.yaml) + - [go-test-darwin.yaml] + - [go-test-linux.yaml] + - [go-test-windows.yaml] +- [go-test-coverage] + - [go-test-coverage configuration] + - [go-test-coverage badge] + +[go-test-darwin.yaml]: ../workflows/README.md#go-test-darwinyaml +[go-test-linux.yaml]: ../workflows/README.md#go-test-linuxyaml +[go-test-windows.yaml]: ../workflows/README.md#go-test-windowsyaml +[testcoverage.yaml]: testcoverage.yaml +[go-test-coverage]: https://github.com/vladopajic/go-test-coverage +[go-test-coverage configuration]: https://github.com/vladopajic/go-test-coverage?tab=readme-ov-file#config +[go-test-coverage badge]: https://github.com/vladopajic/go-test-coverage/blob/main/docs/badge.md diff --git a/.github/linters/README.md b/.github/linters/README.md index 4f67b3b..7bc3d2e 100644 --- a/.github/linters/README.md +++ b/.github/linters/README.md @@ -2,27 +2,53 @@ ## .checkov.yaml -- Used by [???](https://) +- [.checkov.yaml] +- Used by [lint-workflows.yaml] +- [checkov] + - [checkov configuration] ## .golangci.yaml -- Used by [golangci-lint.yaml](../workflows/golangci-lint.yaml) -- [golangci-lint](https://golangci-lint.run/) - - [Configuration](https://golangci-lint.run/usage/configuration/) +- [.golangci.yaml] +- Used by [golangci-lint.yaml] +- [golangci-lint] + - [golangci-lint configuration] ## .jscpd.json -- Used by -- [Options](https://github.com/kucherenko/jscpd/tree/master/apps/jscpd#options) -- Example: - - ```json - { - "ignore": [ - "**/*.go,**/go-test*.yaml" - ], - "threshold": 10 - } - ``` +- [.jscpd.json] +- Used by [lint-workflows.yaml] +- [jscpd] + - [jscpd configuration] + - Example: + + ```json + { + "ignore": [ + "**/*.go,**/go-test*.yaml" + ], + "threshold": 10 + } + ``` ## .yaml-lint.yml + +- [.yaml-lint.yml] +- Used by [lint-workflows.yaml] +- [yaml-lint] + - [yaml-lint configuration] + +[.checkov.yaml]: .checkov.yaml +[.golangci.yaml]: .golangci.yaml +[.jscpd.json]: .jscpd.json +[.yaml-lint.yml]: .yaml-lint.yml +[checkov configuration]: https://www.checkov.io/2.Basics/CLI%20Command%20Reference.html +[checkov]: https://www.checkov.io/ +[golangci-lint configuration]: https://golangci-lint.run/usage/configuration/ +[golangci-lint.yaml]: ../workflows/README.md#golangci-lintyaml +[golangci-lint]: https://golangci-lint.run/ +[jscpd configuration]: https://github.com/kucherenko/jscpd/tree/master/apps/jscpd#options +[jscpd]: https://github.com/kucherenko/jscpd +[lint-workflows.yaml]: ../workflows/README.md#lint-workflowsyaml +[yaml-lint configuration]: https://yamllint.readthedocs.io/en/stable/configuration.html +[yaml-lint]: https://github.com/adrienverge/yamllint diff --git a/.github/workflows/README.md b/.github/workflows/README.md index 85ff789..c690e31 100644 --- a/.github/workflows/README.md +++ b/.github/workflows/README.md @@ -2,72 +2,204 @@ ## add-labels-standardized.yaml -- [GitHub Action](add-labels-standardized.yaml) - - uses [senzing-factory/build-resources/...add-labels-to-issue.yaml)](https://github.com/senzing-factory/build-resources/blob/main/.github/workflows/add-labels-to-issue.yaml) +When issues are opened, +this action adds appropriate labels to the issue. +(e.g. "triage", "customer-submission") + +- [Add Labels Standardized GitHub action] + - Uses: [senzing-factory/build-resources/.../add-labels-to-issue.yaml] ## add-to-project-garage-dependabot.yaml -- [GitHub Action](add-to-project-garage-dependabot.yaml) - - uses [senzing-factory/build-resources/.../add-to-project-dependabot.yaml](https://github.com/senzing-factory/build-resources/blob/main/.github/workflows/add-to-project-dependabot.yaml) +When a Dependabot Pull Request (PR) is made against `main` branch, +this action adds the PR to the "Garage" project board as "In Progress". + +- [Add to Project Garage Dependabot GitHub action] + - Uses: [senzing-factory/build-resources/.../add-to-project-dependabot.yaml] ## add-to-project-garage.yaml -- [GitHub Action](add-to-project-garage.yaml) - - uses [senzing-factory/build-resources/.../add-to-project-dependabot.yaml](https://github.com/senzing-factory/build-resources/blob/main/.github/workflows/add-to-project.yaml) +When an issue is created, +this action adds the issue to the "Garage" board as "Backlog". + +- [Add to Project Garage GitHub action] + - Uses: [senzing-factory/build-resources/.../add-to-project.yaml] ## dependabot-approve-and-merge.yaml -- [GitHub Action](dependabot-approve-and-merge.yaml) - - uses [senzing-factory/build-resources/.../dependabot-approve-and-merge.yaml](https://github.com/senzing-factory/build-resources/blob/main/.github/workflows/dependabot-approve-and-merge.yaml) +When a Dependabot Pull Request (PR) is made against the `main` branch, +this action determines if it should be automatically approved and merged into the `main` branch. +Once this action occurs [move-pr-to-done-dependabot.yaml] moves the PR on the "Garage" project board to "Done". + +- [Dependabot Approve and Merge GitHub action] + - Uses: [senzing-factory/build-resources/.../dependabot-approve-and-merge.yaml] ## docker-build-container.yaml -- [GitHub Action](docker-build-container.yaml) - - uses [senzing-factory/github-action-docker-buildx-build](https://github.com/senzing-factory/github-action-docker-buildx-build) +When a Pull Request is made against the `main` branch, +this action verifies that the `Dockerfile` can be successfully built. + +*Note:* The Docker image is **not** pushed to [DockerHub]. + +- [Docker Build Container GitHub action] + - Uses: [senzing-factory/github-action-docker-buildx-build] ## docker-push-containers-to-dockerhub.yaml -- [GitHub Action](docker-push-containers-to-dockerhub.yaml) - - uses [senzing-factory/github-action-docker-buildx-build](https://github.com/senzing-factory/github-action-docker-buildx-build) +After a [Semantic Version] release is created, +this action builds Docker images on multiple architectures and pushes the Docker images to [DockerHub]. + +- [Docker Push Containers to DockerHub GitHub action] + - Uses: [senzing-factory/github-action-docker-buildx-build] ## golangci-lint.yaml -- [GitHub Action](golangci-lint.yaml) - - uses [golangci/golangci-lint-action](https://github.com/golangci/golangci-lint-action) +When a change is committed to GitHub or a Pull Request is made against the `main` branch, +this action runs [golangci-lint] to run multiple linters against the code. + +- [Golangci Lint GitHub action] + - Configuration: + - [.golangci.yaml] + - Uses: + - [actions/checkout] + - [senzing-factory/github-action-install-senzing-api] + - [actions/setup-go] + - [golangci/golangci-lint-action] ## go-proxy-pull.yaml -- [GitHub Action](go-proxy-pull.yaml) - - uses [andrewslotin/go-proxy-pull-action](https://github.com/andrewslotin/go-proxy-pull-action) +After a [Semantic Version] release is created, +this action expedites the Go publishing process. + +- [Go Proxy Pull GitHub action] + - Uses: [andrewslotin/go-proxy-pull-action] ## go-test-darwin.yaml -- [GitHub Action](go-test-darwin.yaml) +When a Pull Request is made against the `main` branch, +this action runs `go test` with coverage testing on macOS. + +- [Go Test Darwin GitHub action] + - Configuration: [testcoverage.yaml] + - Uses: + - [actions/checkout] + - [actions/setup-go] + - [gotesttools/gotestfmt-action] + - [senzing-factory/github-action-install-senzing-api] + - [actions/upload-artifact] + - [senzing-factory/build-resources/.../go-coverage.yaml] ## go-test-linux.yaml -- [GitHub Action](go-test-linux.yaml) +When a change is committed to GitHub or a Pull Request is made against the `main` branch, +this action runs `go test` with coverage testing on Linux. + +- [Go Test Linux GitHub action] + - Configuration: [testcoverage.yaml] + - Uses: + - [actions/checkout] + - [actions/setup-go] + - [gotesttools/gotestfmt-action] + - [senzing-factory/github-action-install-senzing-api] + - [actions/upload-artifact] + - [senzing-factory/build-resources/.../go-coverage.yaml] ## go-test-windows.yaml -- [GitHub Action](go-test-windows.yaml) +When a Pull Request is made against the `main` branch, +this action runs `go test` with coverage testing on Windows. + +- [Go Test Windows GitHub action] + - Configuration: [testcoverage.yaml] + - Uses: + - [actions/checkout] + - [actions/setup-go] + - [gotesttools/gotestfmt-action] + - [senzing-factory/github-action-install-senzing-api] + - [actions/upload-artifact] + - [senzing-factory/build-resources/.../go-coverage.yaml] ## lint-workflows.yaml -- [GitHub Action](lint-workflows.yaml) - - uses [senzing-factory/build-resources/.../lint-workflows.yaml](https://github.com/senzing-factory/build-resources/blob/main/.github/workflows/lint-workflows.yaml) +When a change is committed to GitHub or a Pull Request is made against the `main` branch, +this action runs [super-linter] to run multiple linters against the code. + +- [Lint Workflows GitHub action] + - Configuration: + - [.checkov.yaml] + - [.jscpd.json] + - [.yaml-lint.yml] + - Uses: [senzing-factory/build-resources/.../lint-workflows.yaml] ## make-go-github-file.yaml -- [GitHub Action](make-go-github-file.yaml) - - uses [senzing-factory/build-resources/.../make-go-github-file.yaml](https://github.com/senzing-factory/build-resources/blob/main/.github/workflows/make-go-github-file.yaml) +After a [Semantic Version] release is created, +this action creates a Pull Request for an updated [github.go] file +for the **next** Semantic Version release by increasing the Semantic Version's Patch value. + +- [Make Go GitHub File GitHub action] + - Uses: [senzing-factory/build-resources/.../make-go-github-file.yaml] ## make-go-tag.yaml -- [GitHub Action](make-go-tag.yaml) - - uses [senzing-factory/github-action-make-go-tag](https://github.com/senzing-factory/github-action-make-go-tag) +After a [Semantic Version] release is created, +this action creates a tag in the form `vM.m.P` using the SHA of the `M.m.P` release. +The `v` prefix is standard usage in [Go]. + +- [Make Go Tag GitHub action] + - Uses: + - [actions/checkout] + - [senzing-factory/github-action-make-go-tag] ## move-pr-to-done-dependabot.yaml -- [GitHub Action](move-pr-to-done-dependabot.yaml) - - uses [senzing-factory/build-resources/.../move-pr-to-done-dependabot.yaml](https://github.com/senzing-factory/build-resources/blob/main/.github/workflows/move-pr-to-done-dependabot.yaml) +When a Pull Request is merged into the `main` branch, +this action moves the PR on the "Garage" project board to "Done". + +- [Move PR to Done Dependabot GitHub action] + - Uses: [senzing-factory/build-resources/.../move-pr-to-done-dependabot.yaml] + +[.checkov.yaml]: ../linters/README.md#checkovyaml +[.golangci.yaml]: ../linters/README.md#golangciyaml +[.jscpd.json]: ../linters/README.md#jscpdjson +[.yaml-lint.yml]: ../linters/README.md#yaml-lintyml +[actions/checkout]: https://github.com/actions/checkout +[actions/setup-go]: https://github.com/actions/setup-go +[actions/upload-artifact]: https://github.com/actions/upload-artifact +[Add Labels Standardized GitHub action]: add-labels-standardized.yaml +[Add to Project Garage Dependabot GitHub action]: add-to-project-garage-dependabot.yaml +[Add to Project Garage GitHub action]: add-to-project-garage.yaml +[andrewslotin/go-proxy-pull-action]: https://github.com/andrewslotin/go-proxy-pull-action +[Dependabot Approve and Merge GitHub action]: dependabot-approve-and-merge.yaml +[Docker Build Container GitHub action]: docker-build-container.yaml +[Docker Push Containers to DockerHub GitHub action]: docker-push-containers-to-dockerhub.yaml +[DockerHub]: https://hub.docker.com/ +[github.go]: ../../cmd/github.go +[Go Proxy Pull GitHub action]: go-proxy-pull.yaml +[Go Test Darwin GitHub action]: go-test-darwin.yaml +[Go Test Linux GitHub action]: go-test-linux.yaml +[Go Test Windows GitHub action]: go-test-windows.yaml +[Go]: https://go.dev/ +[Golangci Lint GitHub action]: golangci-lint.yaml +[golangci-lint]: https://github.com/golangci/golangci-lint +[golangci/golangci-lint-action]: https://github.com/golangci/golangci-lint-action +[gotesttools/gotestfmt-action]: https://github.com/gotesttools/gotestfmt-action +[Lint Workflows GitHub action]: lint-workflows.yaml +[Make Go GitHub File GitHub action]: make-go-github-file.yaml +[Make Go Tag GitHub action]: make-go-tag.yaml +[Move PR to Done Dependabot GitHub action]: move-pr-to-done-dependabot.yaml +[move-pr-to-done-dependabot.yaml]: move-pr-to-done-dependabotyaml +[Semantic Version]: https://semver.org/ +[senzing-factory/build-resources/.../add-labels-to-issue.yaml]: https://github.com/senzing-factory/build-resources/blob/main/.github/workflows/add-labels-to-issue.yaml +[senzing-factory/build-resources/.../add-to-project-dependabot.yaml]: https://github.com/senzing-factory/build-resources/blob/main/.github/workflows/add-to-project-dependabot.yaml +[senzing-factory/build-resources/.../add-to-project.yaml]: https://github.com/senzing-factory/build-resources/blob/main/.github/workflows/add-to-project.yaml +[senzing-factory/build-resources/.../dependabot-approve-and-merge.yaml]: https://github.com/senzing-factory/build-resources/blob/main/.github/workflows/dependabot-approve-and-merge.yaml +[senzing-factory/build-resources/.../go-coverage.yaml]: https://github.com/senzing-factory/build-resources/blob/main/.github/workflows/go-coverage.yaml +[senzing-factory/build-resources/.../lint-workflows.yaml]: https://github.com/senzing-factory/build-resources/blob/main/.github/workflows/lint-workflows.yaml +[senzing-factory/build-resources/.../make-go-github-file.yaml]: https://github.com/senzing-factory/build-resources/blob/main/.github/workflows/make-go-github-file.yaml +[senzing-factory/build-resources/.../move-pr-to-done-dependabot.yaml]: https://github.com/senzing-factory/build-resources/blob/main/.github/workflows/move-pr-to-done-dependabot.yaml +[senzing-factory/github-action-docker-buildx-build]: https://github.com/senzing-factory/github-action-docker-buildx-build +[senzing-factory/github-action-install-senzing-api]: https://github.com/senzing-factory/github-action-install-senzing-api +[senzing-factory/github-action-make-go-tag]: https://github.com/senzing-factory/github-action-make-go-tag +[super-linter]: https://github.com/super-linter/super-linter +[testcoverage.yaml]: ../coverage/README.md#testcoverageyaml diff --git a/Makefile b/Makefile index b531de3..6304837 100644 --- a/Makefile +++ b/Makefile @@ -10,7 +10,8 @@ include makefiles/osdetect.mk # "Simple expanded" variables (':=') -PROGRAM_NAME := $(shell basename `git rev-parse --show-toplevel`) # Name of the GIT repository. +# PROGRAM_NAME is the name of the GIT repository. +PROGRAM_NAME := $(shell basename `git rev-parse --show-toplevel`) MAKEFILE_PATH := $(abspath $(firstword $(MAKEFILE_LIST))) MAKEFILE_DIRECTORY := $(shell dirname $(MAKEFILE_PATH)) TARGET_DIRECTORY := $(MAKEFILE_DIRECTORY)/target @@ -131,6 +132,13 @@ check-coverage: .PHONY: run run: run-osarch-specific +# ----------------------------------------------------------------------------- +# Documentation +# ----------------------------------------------------------------------------- + +.PHONY: documentation +documentation: documentation-osarch-specific + # ----------------------------------------------------------------------------- # Clean # ----------------------------------------------------------------------------- diff --git a/README.md b/README.md index 094c04a..e35fae0 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,9 @@ # go-cmdhelping -If you are beginning your journey with -[Senzing](https://senzing.com/), -please start with -[Senzing Quick Start guides](https://docs.senzing.com/quickstart/). - -You are in the -[Senzing Garage](https://github.com/senzing-garage) -where projects are "tinkered" on. +If you are beginning your journey with [Senzing], +please start with [Senzing Quick Start guides]. + +You are in the [Senzing Garage] where projects are "tinkered" on. Although this GitHub repository may help you understand an approach to using Senzing, it's not considered to be "production ready" and is not considered to be part of the Senzing product. Heck, it may not even be appropriate for your application of Senzing! @@ -28,7 +24,6 @@ the recommendation is not to use it yet. [![Go Report Card](https://goreportcard.com/badge/github.com/senzing-garage/go-cmdhelping)](https://goreportcard.com/report/github.com/senzing-garage/go-cmdhelping) [![License](https://img.shields.io/badge/License-Apache2-brightgreen.svg)](https://github.com/senzing-garage/go-cmdhelping/blob/main/LICENSE) -[![gosec.yaml](https://github.com/senzing-garage/go-cmdhelping/actions/workflows/gosec.yaml/badge.svg)](https://github.com/senzing-garage/go-cmdhelping/actions/workflows/gosec.yaml) [![go-test-linux.yaml](https://github.com/senzing-garage/go-cmdhelping/actions/workflows/go-test-linux.yaml/badge.svg)](https://github.com/senzing-garage/go-cmdhelping/actions/workflows/go-test-linux.yaml) [![go-test-darwin.yaml](https://github.com/senzing-garage/go-cmdhelping/actions/workflows/go-test-darwin.yaml/badge.svg)](https://github.com/senzing-garage/go-cmdhelping/actions/workflows/go-test-darwin.yaml) [![go-test-windows.yaml](https://github.com/senzing-garage/go-cmdhelping/actions/workflows/go-test-windows.yaml/badge.svg)](https://github.com/senzing-garage/go-cmdhelping/actions/workflows/go-test-windows.yaml) @@ -53,6 +48,20 @@ for an example of use. ## References -- [Development](docs/development.md) -- [Errors](docs/errors.md) -- [Examples](docs/examples.md) +1. [API documentation] +1. [Development] +1. [Errors] +1. [Examples] +1. Related artifacts: + 1. [DockerHub] + 1. [Helm Chart] + +[API documentation]: https://pkg.go.dev/github.com/senzing-garage/template-go +[Development]: docs/development.md +[DockerHub]: https://hub.docker.com/r/senzing/template-go +[Errors]: docs/errors.md +[Examples]: docs/examples.md +[Helm Chart]: https://github.com/senzing-garage/charts/tree/main/charts/template-go +[Senzing Garage]: https://github.com/senzing-garage-garage +[Senzing Quick Start guides]: https://docs.senzing.com/quickstart/ +[Senzing]: https://senzing.com/ diff --git a/docs/development.md b/docs/development.md index 36e6892..b10e8cb 100644 --- a/docs/development.md +++ b/docs/development.md @@ -2,7 +2,7 @@ ## Install Go -1. See Go's [Download and install](https://go.dev/doc/install) +1. See Go's [Download and install]. ## Install Senzing C library @@ -13,8 +13,7 @@ Since the Senzing library is a prerequisite, it must be installed first. 1. `/opt/senzing/g2/sdk/c` 1. `/etc/opt/senzing` -1. If not installed, see - [How to Install Senzing for Go Development](https://github.com/senzing-garage/knowledge-base/blob/main/HOWTO/install-senzing-for-go-development.md). +1. If not installed, see [How to Install Senzing for Go Development]. ## Install Git repository @@ -28,150 +27,155 @@ Since the Senzing library is a prerequisite, it must be installed first. ``` -1. Using the environment variables values just set, follow steps in - [clone-repository](https://github.com/senzing-garage/knowledge-base/blob/main/HOWTO/clone-repository.md) to install the Git repository. +1. Using the environment variables values just set, follow + steps in [clone-repository] to install the Git repository. -## Build +## Dependencies -1. Build the binaries. +1. A one-time command to install dependencies needed for `make` targets. Example: ```console cd ${GIT_REPOSITORY_DIR} - make build + make dependencies-for-make ``` -1. The binaries will be found in ${GIT_REPOSITORY_DIR}/target. +1. Install dependencies needed for [Go] code. Example: ```console - tree ${GIT_REPOSITORY_DIR}/target + cd ${GIT_REPOSITORY_DIR} + make dependencies ``` -## Run +## Build -1. Run the binary. +1. Build the binaries. Example: ```console - ${GIT_REPOSITORY_DIR}/target/linux/go-cmdhelping + cd ${GIT_REPOSITORY_DIR} + make clean build ``` -1. Clean up. +1. The binaries will be found in the `${GIT_REPOSITORY_DIR}/target` directory. Example: ```console - cd ${GIT_REPOSITORY_DIR} - make clean + tree ${GIT_REPOSITORY_DIR}/target ``` -## Test +## Run -1. Run Go tests. - Example: +1. Run the binary. + Examples: - ```console - cd ${GIT_REPOSITORY_DIR} - make test + 1. linux - ``` + ```console + ${GIT_REPOSITORY_DIR}/target/linux-amd64/template-go -## Documentation + ``` -1. Start `godoc` documentation server. - Example: + 1. macOS - ```console - cd ${GIT_REPOSITORY_DIR} - godoc + ```console + ${GIT_REPOSITORY_DIR}/target/darwin-amd64/template-go - ``` + ``` -1. Visit [localhost:6060](http://localhost:6060) -1. Senzing documentation will be in the "Third party" section. - `github.com` > `senzing` > `go-cmdhelping` + 1. windows -1. When a versioned release is published with a `v0.0.0` format tag, -the reference can be found by clicking on the following badge at the top of the README.md page: -[![Go Reference](https://pkg.go.dev/badge/github.com/senzing-garage/go-cmdhelping.svg)](https://pkg.go.dev/github.com/senzing-garage/go-cmdhelping) + ```console + ${GIT_REPOSITORY_DIR}/target/windows-amd64/template-go -## Docker + ``` -1. Use make target to run a docker images that builds RPM and DEB files. +1. Clean up. Example: ```console cd ${GIT_REPOSITORY_DIR} - make docker-build + make clean ``` -1. Run docker container. +## Lint + +1. Run Go tests. Example: ```console - docker run \ - --rm \ - senzing/go-cmdhelping + cd ${GIT_REPOSITORY_DIR} + make lint ``` -## Package - -### Package RPM and DEB files +## Test -1. Use make target to run a docker images that builds RPM and DEB files. +1. Run Go tests. Example: ```console cd ${GIT_REPOSITORY_DIR} - make package + make clean setup test ``` -1. The results will be in the `${GIT_REPOSITORY_DIR}/target` directory. - Example: +## Coverage - ```console - tree ${GIT_REPOSITORY_DIR}/target +Create a code coverage map. - ``` - -### Test DEB package on Ubuntu - -1. Determine if `go-cmdhelping` is installed. +1. Run Go tests. Example: ```console - apt list --installed | grep go-cmdhelping + cd ${GIT_REPOSITORY_DIR} + make clean setup coverage ``` -1. :pencil2: Install `go-cmdhelping`. + A web-browser will show the results of the coverage. + The goal is to have over 80% coverage. + Anything less needs to be reflected in [testcoverage.yaml]. + +## Documentation + +1. Start [godoc] documentation server. Example: ```console - cd ${GIT_REPOSITORY_DIR}/target - sudo apt install ./go-cmdhelping-0.0.0.deb + cd ${GIT_REPOSITORY_DIR} + make clean documentation ``` -1. Run command. - Example: +1. If a web page doesn't appear, visit [localhost:6060]. +1. Senzing documentation will be in the "Third party" section. + `github.com` > `senzing` > `go-cmdhelping` - ```console - go-cmdhelping +1. When a versioned release is published with a `v0.0.0` format tag, +the reference can be found by clicking on the following badge at the top of the README.md page. +Example: - ``` + [![Go Reference](https://pkg.go.dev/badge/github.com/senzing-garage/go-cmdhelping.svg)](https://pkg.go.dev/github.com/senzing-garage/go-cmdhelping-go) -1. Remove `go-cmdhelping` from system. - Example: +1. To stop the `godoc` server, run ```console - sudo apt-get remove go-cmdhelping + cd ${GIT_REPOSITORY_DIR} + make clean ``` + +[clone-repository]: https://github.com/senzing-garage/knowledge-base/blob/main/HOWTO/clone-repository.md +[Download and install]: https://go.dev/doc/install +[Go]: https://go.dev/ +[godoc]: https://pkg.go.dev/golang.org/x/tools/cmd/godoc +[How to Install Senzing for Go Development]: https://github.com/senzing-garage/knowledge-base/blob/main/HOWTO/install-senzing-for-go-development.md +[localhost:6060]: http://localhost:6060/pkg/github.com/senzing-garage/template-go/ +[testcoverage.yaml]: ../.github/coverage/testcoverage.yaml diff --git a/docs/examples.md b/docs/examples.md index 3cb6b8d..aeb1c75 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -8,4 +8,4 @@ The following examples require initialization described in ## Examples of Docker The following examples require initialization described in -[Demonstrate using Docker](../README.md#demonstrate-using-docker). \ No newline at end of file +[Demonstrate using Docker](../README.md#demonstrate-using-docker). diff --git a/makefiles/darwin.mk b/makefiles/darwin.mk index a95e22d..5475be3 100644 --- a/makefiles/darwin.mk +++ b/makefiles/darwin.mk @@ -19,6 +19,7 @@ clean-osarch-specific: @rm -f $(MAKEFILE_DIRECTORY)/coverage.html || true @rm -f $(MAKEFILE_DIRECTORY)/cover.out || true @rm -fr $(TARGET_DIRECTORY) || true + @pkill godoc || true .PHONY: coverage-osarch-specific @@ -29,6 +30,12 @@ coverage-osarch-specific: @open file://$(MAKEFILE_DIRECTORY)/coverage.html +.PHONY: documentation-osarch-specific +documentation-osarch-specific: + godoc & + @open http://localhost:6060 + + .PHONY: hello-world-osarch-specific hello-world-osarch-specific: @echo "Hello World, from darwin." diff --git a/makefiles/linux.mk b/makefiles/linux.mk index b8ac3ae..f1929c6 100644 --- a/makefiles/linux.mk +++ b/makefiles/linux.mk @@ -19,6 +19,7 @@ clean-osarch-specific: @rm -f $(MAKEFILE_DIRECTORY)/coverage.html || true @rm -f $(MAKEFILE_DIRECTORY)/cover.out || true @rm -fr $(TARGET_DIRECTORY) || true + @pkill godoc || true .PHONY: coverage-osarch-specific @@ -29,6 +30,12 @@ coverage-osarch-specific: @xdg-open $(MAKEFILE_DIRECTORY)/coverage.html +.PHONY: documentation-osarch-specific +documentation-osarch-specific: + godoc & + xdg-open http://localhost:6060 + + .PHONY: hello-world-osarch-specific hello-world-osarch-specific: @echo "Hello World, from linux." diff --git a/makefiles/windows.mk b/makefiles/windows.mk index 8d05922..9a65844 100644 --- a/makefiles/windows.mk +++ b/makefiles/windows.mk @@ -20,13 +20,20 @@ clean-osarch-specific: del /F /S /Q $(MAKEFILE_DIRECTORY)/coverage.html del /F /S /Q $(MAKEFILE_DIRECTORY)/cover.out del /F /S /Q $(TARGET_DIRECTORY) + taskkill /f /t/im godoc .PHONY: coverage-osarch-specific coverage-osarch-specific: @go test -v -coverprofile=coverage.out -p 1 ./... @go tool cover -html="coverage.out" -o coverage.html - @xdg-open file://$(MAKEFILE_DIRECTORY)/coverage.html + @explorer file://$(MAKEFILE_DIRECTORY)/coverage.html + + +.PHONY: documentation-osarch-specific +documentation-osarch-specific: + @start /b godoc + @explorer http://localhost:6060 .PHONY: hello-world-osarch-specific