From 7a0067d59d6d0fec6b50c35b6328cbb557eef2fb Mon Sep 17 00:00:00 2001 From: drdr xp Date: Sat, 21 Nov 2020 19:54:16 +0800 Subject: [PATCH] refactor: doc: apply gotmpl --- .github/settings-sample.yml | 10 +++ .github/workflows/golangci-lint.yml | 30 ++++++++ .github/workflows/test.yml | 38 ++++++++++ .gitignore | 5 +- .travis.yml | 20 ++++-- LICENSE | 2 +- Makefile | 82 +-------------------- common.mk | 106 ++++++++++++++++++++++++++++ docs/badges.md | 9 +++ scripts/build_md.py | 58 +++++++++++++++ scripts/requirements.txt | 3 + 11 files changed, 274 insertions(+), 89 deletions(-) create mode 100644 .github/settings-sample.yml create mode 100644 .github/workflows/golangci-lint.yml create mode 100644 .github/workflows/test.yml create mode 100644 common.mk create mode 100644 docs/badges.md create mode 100755 scripts/build_md.py create mode 100644 scripts/requirements.txt diff --git a/.github/settings-sample.yml b/.github/settings-sample.yml new file mode 100644 index 0000000..808d5dc --- /dev/null +++ b/.github/settings-sample.yml @@ -0,0 +1,10 @@ +# Usage copy this to settings.yml + +_extends: gh-config + + +repository: + name: name + description: desc + homepage: https://openacid.github.io/ + topics: go, golang diff --git a/.github/workflows/golangci-lint.yml b/.github/workflows/golangci-lint.yml new file mode 100644 index 0000000..a300bcb --- /dev/null +++ b/.github/workflows/golangci-lint.yml @@ -0,0 +1,30 @@ +name: golangci-lint +on: + push: + tags: + - v* + branches: + - '*' + pull_request: +jobs: + golangci: + name: lint + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + + - name: golangci-lint + uses: golangci/golangci-lint-action@v2 + with: + # Required: the version of golangci-lint is required and must be specified without patch version: we always use the latest patch version. + version: v1.29 + + # Optional: working directory, useful for monorepos + # working-directory: somedir + + # disable staticcheck: + # SA1019: package github.com/golang/protobuf/proto is deprecated: Use the "google.golang.org/protobuf/proto" package instead + args: --issues-exit-code=0 --exclude SA1019 + + # Optional: show only new issues if it's a pull request. The default value is `false`. + # only-new-issues: true diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml new file mode 100644 index 0000000..b7db341 --- /dev/null +++ b/.github/workflows/test.yml @@ -0,0 +1,38 @@ +name: test +on: + push: + pull_request: + +jobs: + test: + strategy: + matrix: + go-version: + - 1.14.x + - 1.15.x + os: + - ubuntu-latest + - macos-latest + - windows-latest + + runs-on: ${{ matrix.os }} + + steps: + - name: Install Go + uses: actions/setup-go@v2 + with: + go-version: ${{ matrix.go-version }} + + - name: checkout + uses: actions/checkout@v2 + + - name: cache + uses: actions/cache@v2 + with: + path: ~/go/pkg/mod + key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }} + restore-keys: | + ${{ runner.os }}-go- + + - name: test + run: go test ./... diff --git a/.gitignore b/.gitignore index f1c181e..66fd13c 100644 --- a/.gitignore +++ b/.gitignore @@ -5,8 +5,11 @@ *.so *.dylib -# Test binary, build with `go test -c` +# Test binary, built with `go test -c` *.test # Output of the go coverage tool, specifically when used with LiteIDE *.out + +# Dependency directories (remove the comment below to include it) +# vendor/ diff --git a/.travis.yml b/.travis.yml index 7fa2695..56fc3e1 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,10 +1,18 @@ language: go + go: - - 1.11.x - - 1.12.x - - tip + - 1.14.x + - 1.15.x + # - tip + script: - make travis -env: - global: - - secure: viNyH2p416THRmkiQSpRpB7NrSb5Aoy7TIfE7LiWyDJjAYIsi8eBHhTGVak4sg5VcQFRC/ReYHFwnFD/ZnsSBh4iRTLaX3BdmvgTHOYC7mqv87nRYqncJMtnBV7l6gyi2b2WcMwlkXGKR57UVs+rVlrZ2frKYoht7IhVGCXcn075FXkmq0CP+m8Z2nqcIC2TDzJxu7TLYpryuYb6NB5delQ7NcITE8yT0y9hZa6uCz5U3k1+Y0i//3fkBdahTd9023QANiROCtR1ZkMjrFzugsDG2jiByHm6Ho54NMuBSpGfYfr0LlrZ3fytAFCZ03olPPeQyfaD5CPc4cdGqVRP0NvOW68sSkKoobUULehC7p893fA1hSnPu2gH8Hf67kiTPDZ/SdYVlPFzBYtYvAhjyMOJ0srycO3l/4Ixlwe0fuUtBKnmWSsiGLOEGKEwHb62ViTIy6DPvcduNqK5/B5V0vCFkXfA3+NyDrydntW9/+nDqfUE5R6kZ60EvbaltPBZc+vdUzFUliLDuk8oWaOMhlKaKvsSWI3Q9wNwgkceUdcrDx4v18y+LMRrMCvE/kQGBZJDrEB6QMLfbdav13m3L9yQt8epFfwb9jGXqtNm6igHQMiRJAavIRyv4QlvoQoiI2zDnwyDv5kzrMadr2zxN0U0Cp6JtYfs/PqQa9Aea2g= + +after_success: + - make coveralls + +# private repo requires a crypted token: +# env: +# global: +# # coveralls token +# secure: fJOPOuwBaZ59iQA1VskxZ3h08Nt5CjGbz5PdrZVT/v5UCG7DOLuVTx3x0Tb+gR9AG9lB8Fqpsnm0jjbBAPvOnyn1KIJDuK9Xj2PvKT78vhJ/SyCnn0BAinmxu9hZqghvyWIzeM8RrA3IrvmnoSUTdE1jnTC7McJ7np6cTRGO9Xe6b4mOO1xQOHJFMyTBFvA84uSKZPbuUHCrh19YH7NKrA4MKunX49R+niEFlFEM4oNM/2FXMca+4+OdlGNJmPkG0kV5exP87ihfqI3Q++9v3Z8SR0KOblL6yRBspaRDHmfKxuGx/YEf71pu0yu7nyT7uVeIABTz5SLrqX2Fhb/cpKb7iqCBQ+ifvgpd86pkfhrPUOsIO9N6pieNxmb+aCNm5WBJ2AaT1zrrfthpfbXvEl66K209rUDL0PV1n/u1pAgY5q7DQD5YuOnyAJNPBNQYYzJnZ+X1GjSNrHKOQPjXmrgwkq7KPVlDoqiaJAh97YwUmjXaULKYOm9JBPwVaToEUeCxzK82ZZRwa4YiYl3MLpJb+SvDMl97hgc58lolfg01wHgLYAT901bbq+qsrQZY4pkW9nDGvBuJg0Mru1bu6hqk/tUA7G4amh2y/5lJxxELednfnyzQ6fBeXKb0FVOTN9xRuFBkpRL1Drmbz3y6J2flAcdpJ4KgAMUP/941J6o= diff --git a/LICENSE b/LICENSE index 568177a..7c13c2d 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2019 openacid +Copyright (c) 2020 openacid Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/Makefile b/Makefile index 2f82e7f..31ea6a8 100644 --- a/Makefile +++ b/Makefile @@ -1,81 +1 @@ -# `grep -v` does not work on travis. No time to find out why -- xp 2019 Feb 22 -PKGS := $(shell go list ./... | grep -v "^github.com/openacid/low/\(vendor\|prototype\)") - -SRCDIRS := $(shell go list -f '{{.Dir}}' $(PKGS)) - -# gofmt check vendor dir. we need to skip vendor manually -GOFILES := $(shell find $(SRCDIRS) -not -path "*/vendor/*" -name "*.go") -GO := go - -check: test vet gofmt misspell unconvert staticcheck ineffassign unparam - -travis: test vet gofmt misspell unconvert ineffassign unparam coveralls - -test: - $(GO) test -tags debug $(PKGS) - $(GO) test $(PKGS) - -vet: | test - $(GO) vet $(PKGS) - -staticcheck: - $(GO) get honnef.co/go/tools/cmd/staticcheck - # ST1016: methods on the same type should have the same receiver name - # .pb.go have this issue. - staticcheck -checks all,-ST1016 $(PKGS) - -misspell: - $(GO) get github.com/client9/misspell/cmd/misspell - find $(SRCDIRS) -name '*.go' -or -name '*.md' | grep -v "\bvendor/" | xargs misspell \ - -locale US \ - -error - misspell \ - -locale US \ - -error \ - *.md *.go - -unconvert: - $(GO) get github.com/mdempsky/unconvert - unconvert -v $(PKGS) - -ineffassign: - $(GO) get github.com/gordonklaus/ineffassign - find $(SRCDIRS) -name '*.go' | grep -v "\bvendor/" | xargs ineffassign - -pedantic: check errcheck - -unparam: - $(GO) get mvdan.cc/unparam - unparam ./... - -errcheck: - $(GO) get github.com/kisielk/errcheck - errcheck $(PKGS) - -gofmt: - @echo Checking code is gofmted - @test -z "$(shell gofmt -s -l -d -e $(GOFILES) | tee /dev/stderr)" - -ben: test - $(GO) test ./... -run=none -bench=. -benchmem - -gen: - $(GO) generate ./... - -readme: - python ./scripts/build_readme.py - # brew install nodejs - # npm install -g doctoc - doctoc --title '' --github README.md - -fix: - gofmt -s -w $(GOFILES) - unconvert -v -apply $(PKGS) - - -coveralls: - $(GO) get golang.org/x/tools/cmd/cover - $(GO) get github.com/mattn/goveralls - # enable debug mode to cover must.Be statements - $(GO) test -tags debug -v -covermode=count -coverprofile=coverage.out $(PKGS) - $$HOME/gopath/bin/goveralls -coverprofile=coverage.out -service=travis-ci -repotoken $$COVERALLS_TOKEN +include common.mk diff --git a/common.mk b/common.mk new file mode 100644 index 0000000..d609d44 --- /dev/null +++ b/common.mk @@ -0,0 +1,106 @@ +# Usage: echo 'include common.mk' > Makefile + +TOP_PKG := $(shell go list .) +NAME := $(shell go list . | awk -F/ '{print $$NF}') +PKGS := $(shell go list ./... | grep -v "^$(TOP_PKG)/\(vendor\|prototype\)") + +# PKGS := github.com/openacid/slimarray/array \ +# github.com/openacid/slimarray/bit \ +# github.com/openacid/slimarray/trie \ + +SRCDIRS := $(shell go list -f '{{.Dir}}' $(PKGS)) + +# gofmt check vendor dir. we need to skip vendor manually +GOFILES := $(shell find $(SRCDIRS) -not -path "*/vendor/*" -name "*.go") +GO := go + +check: test vet gofmt misspell unconvert staticcheck ineffassign unparam + +travis: vet gofmt misspell unconvert ineffassign unparam test + +test: + # fail fast with severe bugs + $(GO) test -short $(PKGS) + $(GO) test -tags debug $(PKGS) + # test release version and generate coverage data for task `coveralls`. + $(GO) test -covermode=count -coverprofile=coverage.out $(PKGS) + +vet: + $(GO) vet $(PKGS) + +staticcheck: + $(GO) get honnef.co/go/tools/cmd/staticcheck + # ST1016: methods on the same type should have the same receiver name + # .pb.go have this issue. + staticcheck -checks all,-ST1016 $(PKGS) + +misspell: + $(GO) get github.com/client9/misspell/cmd/misspell + find $(SRCDIRS) -name '*.go' -or -name '*.md' | grep -v "\bvendor/" | xargs misspell \ + -locale US \ + -error + misspell \ + -locale US \ + -error \ + *.md *.go + +unconvert: + $(GO) get github.com/mdempsky/unconvert + unconvert -v $(PKGS) + +ineffassign: + $(GO) get github.com/gordonklaus/ineffassign + find $(SRCDIRS) -name '*.go' | grep -v "\bvendor/" | xargs ineffassign + +pedantic: check errcheck + +unparam: + $(GO) get mvdan.cc/unparam + unparam ./... + +errcheck: + $(GO) get github.com/kisielk/errcheck + errcheck $(PKGS) + +gofmt: + @echo Checking code is gofmted + @test -z "$(shell gofmt -s -l -d -e $(GOFILES) | tee /dev/stderr)" + +ben: test + $(GO) test ./... -run=none -bench=. -benchmem + +gen: + $(GO) generate ./... + +doc: + # build a markdown version of package doc to embed to README.md + # $(GO) get github.com/robertkrimen/godocdown/godocdown + godocdown . > docs/$(NAME).md + # "package" is the first phrase in a go doc. + # "## Usage" is the start of API section. + cat docs/$(NAME).md | awk '/^package /,/^## Usage/' | grep -v '^## Usage' > docs/$(NAME)-package.md + + +readme: doc + python ./scripts/build_md.py + # brew install nodejs + # npm install -g doctoc + doctoc --title '' --github README.md + +fix: + gofmt -s -w $(GOFILES) + unconvert -v -apply $(PKGS) + + +# local coverage +coverage: + $(GO) test -covermode=count -coverprofile=coverage.out $(PKGS) + go tool cover -func=coverage.out + # go tool cover -html=coverage.out + +# send coverage to coveralls +coveralls: + # this job relies on the output of task test: `-coverprofile=coverage.out` + $(GO) get golang.org/x/tools/cmd/cover + $(GO) get github.com/mattn/goveralls + goveralls -ignore='*.pb.go' -coverprofile=coverage.out -service=travis-ci diff --git a/docs/badges.md b/docs/badges.md new file mode 100644 index 0000000..712942a --- /dev/null +++ b/docs/badges.md @@ -0,0 +1,9 @@ +[![Travis](https://travis-ci.com/openacid/{{ name }}.svg?branch=main)](https://travis-ci.com/openacid/{{ name }}) + +![test](https://github.com/openacid/{{ name }}/workflows/test/badge.svg) + +[![Report card](https://goreportcard.com/badge/github.com/openacid/{{ name }})](https://goreportcard.com/report/github.com/openacid/{{ name }}) +[![Coverage Status](https://coveralls.io/repos/github/openacid/{{ name }}/badge.svg?branch=main&service=github)](https://coveralls.io/github/openacid/{{ name }}?branch=main&service=github) + +[![GoDoc](https://godoc.org/github.com/openacid/{{ name }}?status.svg)](http://godoc.org/github.com/openacid/{{ name }}) +[![Sourcegraph](https://sourcegraph.com/github.com/openacid/{{ name }}/-/badge.svg)](https://sourcegraph.com/github.com/openacid/{{ name }}?badge) diff --git a/scripts/build_md.py b/scripts/build_md.py new file mode 100755 index 0000000..0aa182d --- /dev/null +++ b/scripts/build_md.py @@ -0,0 +1,58 @@ +#!/usr/bin/env python +# coding: utf-8 + +import os +import jinja2 +import subprocess + +def render_j2(tmpl_path, tmpl_vars, output_path): + template_loader = jinja2.FileSystemLoader(searchpath='./') + template_env = jinja2.Environment(loader=template_loader, + undefined=jinja2.StrictUndefined) + template = template_env.get_template(tmpl_path) + + txt = template.render(tmpl_vars) + + with open(output_path, 'w') as f: + f.write(txt) + +def command(cmd, *arguments, **options): + + close_fds = options.get('close_fds', True) + cwd = options.get('cwd', None) + shell = options.get('shell', False) + env = options.get('env', None) + if env is not None: + env = dict(os.environ, **env) + stdin = options.get('stdin', None) + + subproc = subprocess.Popen([cmd] + list(arguments), + close_fds=close_fds, + shell=shell, + cwd=cwd, + env=env, + encoding='utf-8', + stdin=subprocess.PIPE, + stdout=subprocess.PIPE, + stderr=subprocess.PIPE, ) + + out, err = subproc.communicate(input=stdin) + + subproc.wait() + + if subproc.returncode != 0: + raise Exception(subproc.returncode, out, err) + + return out + +if __name__ == "__main__": + pkg = command('go', 'list', '.') + name = pkg.strip().split('/')[-1] + tmpl_vars = { + "name": name + } + + fns = os.listdir('docs') + for fn in fns: + if fn.endswith('.md.j2'): + render_j2('docs/'+fn, tmpl_vars, fn[:-3]) diff --git a/scripts/requirements.txt b/scripts/requirements.txt new file mode 100644 index 0000000..54929d6 --- /dev/null +++ b/scripts/requirements.txt @@ -0,0 +1,3 @@ +semantic_version==2.6.0 +jinja2==2.10.1 +PyYAML==5.1