refactor: doc: apply gotmpl

.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

.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

.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 ./...

.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/

.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=

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

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

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

docs/badges.md

@@ -0,0 +1,9 @@
+[![Travis](https://travis-ci.com/openacid/{{ name }}.svg?branch=main)](https://travis-ci.com/openacid/{{ name }})
+<!-- [![AppVeyor](https://ci.appveyor.com/api/projects/status/m0vvvrru7a1g4mae/branch/main?svg=true)](https://ci.appveyor.com/project/drmingdrmer/{{ name }}/branch/main) -->
+![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)

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])

scripts/requirements.txt

@@ -0,0 +1,3 @@
+semantic_version==2.6.0
+jinja2==2.10.1
+PyYAML==5.1