Skip to content

Commit

Permalink
docs: user documentation on github pages
Browse files Browse the repository at this point in the history
Notice: This is more like an initial documentation site

* Documentation site is powered by Docusaurus.
* gRPC documentation is generated with `protoc-gen-doc`.
* Getting started documentation is the as the quick-start guide, but
  with separate files, so it's easye to navigate and digest the content.
  It really needs a refactoring and we have to write a real user Getting
  Started docoument.
* Enabled `blog` for now, we can turn it off if we don't want to use it.
  Created an example blog post about the v0.1.0-alpha.1 release.
* CNAME: docs.flintlock.dev

Docusaurus: https://docusaurus.io/
protoc-gen-doc: https://github.com/pseudomuto/protoc-gen-doc

Fixes #85
  • Loading branch information
yitsushi committed Nov 4, 2021
1 parent f8622b6 commit 10e2331
Show file tree
Hide file tree
Showing 48 changed files with 10,959 additions and 12 deletions.
12 changes: 11 additions & 1 deletion Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ GOLANGCI_LINT := $(TOOLS_BIN_DIR)/golangci-lint
GINKGO := $(TOOLS_BIN_DIR)/ginkgo
BUF := $(TOOLS_BIN_DIR)/buf
MOCKGEN:= $(TOOLS_BIN_DIR)/mockgen
PROTOC_GEN_DOC := $(TOOLS_BIN_DIR)/protoc-gen-doc
PROTOC_GEN_GO := $(TOOLS_BIN_DIR)/protoc-gen-go
PROTOC_GEN_GO_GRPC := $(TOOLS_BIN_DIR)/protoc-gen-go-grpc
PROTO_GEN_GRPC_GW := $(TOOLS_BIN_DIR)/protoc-gen-grpc-gateway
Expand Down Expand Up @@ -75,7 +76,7 @@ generate-go: $(MOCKGEN) ## Generate Go Code
go generate ./...

.PHONY: generate-proto ## Generate protobuf/grpc code
generate-proto: $(BUF) $(PROTOC_GEN_GO) $(PROTOC_GEN_GO_GRPC) $(PROTO_GEN_GRPC_GW) $(PROTO_GEN_GRPC_OAPI)
generate-proto: $(BUF) $(PROTOC_GEN_GO) $(PROTOC_GEN_GO_GRPC) $(PROTO_GEN_GRPC_GW) $(PROTO_GEN_GRPC_OAPI) $(PROTOC_GEN_DOC)
$(BUF) generate

.PHONY: generate-di ## Generate the dependency injection code
Expand Down Expand Up @@ -147,6 +148,9 @@ $(MOCKGEN): $(TOOLS_DIR)/go.mod # Get and build mockgen
$(PROTOC_GEN_GO): $(TOOLS_DIR)/go.mod
cd $(TOOLS_DIR); go build -tags=tools -o $(subst hack/tools/,,$@) google.golang.org/protobuf/cmd/protoc-gen-go

$(PROTOC_GEN_DOC): $(TOOLS_DIR)/go.mod
cd $(TOOLS_DIR); go build -tags=tools -o $(subst hack/tools/,,$@) github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc

$(PROTOC_GEN_GO_GRPC): $(TOOLS_DIR)/go.mod
cd $(TOOLS_DIR); go build -tags=tools -o $(subst hack/tools/,,$@) google.golang.org/grpc/cmd/protoc-gen-go-grpc

Expand Down Expand Up @@ -174,6 +178,12 @@ $(BUF): $(TOOLS_BIN_DIR) $(BUF_SHARE)
cp $(TOOLS_SHARE_DIR)/buf/bin/* $(TOOLS_BIN_DIR)
rm -rf $(TOOLS_SHARE_DIR)/buf

##@ Docs
.PHONY: docs-build
docs-build: ## Build userdocs site
docs-build: generate-proto
cd ./userdocs && yarn build

##@ Utility

.PHONY: help
Expand Down
8 changes: 7 additions & 1 deletion buf.gen.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -12,4 +12,10 @@ plugins:
- paths=source_relative
- generate_unbound_methods=true
- name: openapiv2
out: api
out: api
- name: doc
out: userdocs/docs/grpc/
opt:
- markdown
- proto.md
- source_relative
2 changes: 1 addition & 1 deletion buf.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -17,4 +17,4 @@ lint:
- PACKAGE_DIRECTORY_MATCH
- PACKAGE_SAME_DIRECTORY
breaking:
use:
use:
4 changes: 2 additions & 2 deletions docs/adr/0004-merge-create-and-update-plan.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# 0. Merge Create and Update Plan into a Single Plan
# 4. Merge Create and Update Plan into a Single Plan
<!-- A short and clear title which is prefixed with the ADR number -->

* Status: accepted
Expand Down Expand Up @@ -26,4 +26,4 @@ It was identified that a simpler solution would be simply merge the plan builder
## Consequences
<!-- Whats the result or impact of this decision. Does anything need to change and are new GitHub issues created as a result -->

N/A
N/A
2 changes: 1 addition & 1 deletion docs/quick-start.md
Original file line number Diff line number Diff line change
Expand Up @@ -268,7 +268,7 @@ There are both GUI and a CLI option.

### grpc-client-cli

Install the [grpcurl](grpcurl).
Install the [grpcurl][grpcurl].

Use the `./hack/scripts/send.sh` script.

Expand Down
25 changes: 19 additions & 6 deletions hack/tools/go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,9 @@ require (
4d63.com/gochecknoglobals v0.0.0-20201008074935-acfc0b28355a // indirect
github.com/BurntSushi/toml v0.3.1 // indirect
github.com/Djarvur/go-err113 v0.0.0-20210108212216-aea10b59be24 // indirect
github.com/Masterminds/goutils v1.1.1 // indirect
github.com/Masterminds/semver v1.5.0 // indirect
github.com/Masterminds/sprig v2.22.0+incompatible // indirect
github.com/OpenPeeDeeP/depguard v1.0.1 // indirect
github.com/alexkohler/prealloc v1.0.0 // indirect
github.com/ashanbrown/forbidigo v1.2.0 // indirect
Expand All @@ -30,6 +32,7 @@ require (
github.com/daixiang0/gci v0.2.8 // indirect
github.com/davecgh/go-spew v1.1.1 // indirect
github.com/denis-tingajkin/go-header v0.4.2 // indirect
github.com/envoyproxy/protoc-gen-validate v0.6.2 // indirect
github.com/esimonov/ifshort v1.0.2 // indirect
github.com/ettle/strcase v0.1.1 // indirect
github.com/fatih/color v1.12.0 // indirect
Expand All @@ -49,6 +52,7 @@ require (
github.com/go-xmlfmt/xmlfmt v0.0.0-20191208150333-d5b6f63a941b // indirect
github.com/gobwas/glob v0.2.3 // indirect
github.com/gofrs/flock v0.8.0 // indirect
github.com/gogo/protobuf v1.3.2 // indirect
github.com/golang/glog v0.0.0-20210429001901-424d2337a529 // indirect
github.com/golang/protobuf v1.5.2 // indirect
github.com/golangci/check v0.0.0-20180506172741-cfe4005ccda2 // indirect
Expand All @@ -62,6 +66,7 @@ require (
github.com/golangci/unconvert v0.0.0-20180507085042-28b1c447d1f4 // indirect
github.com/google/go-cmp v0.5.6 // indirect
github.com/google/subcommands v1.0.1 // indirect
github.com/google/uuid v1.3.0 // indirect
github.com/gordonklaus/ineffassign v0.0.0-20210225214923-2e10b2664254 // indirect
github.com/gostaticanalysis/analysisutil v0.4.1 // indirect
github.com/gostaticanalysis/comment v1.4.1 // indirect
Expand All @@ -70,6 +75,8 @@ require (
github.com/hashicorp/errwrap v1.0.0 // indirect
github.com/hashicorp/go-multierror v1.1.1 // indirect
github.com/hashicorp/hcl v1.0.0 // indirect
github.com/huandu/xstrings v1.3.2 // indirect
github.com/imdario/mergo v0.3.12 // indirect
github.com/inconshreveable/mousetrap v1.0.0 // indirect
github.com/jgautheron/goconst v1.5.1 // indirect
github.com/jingyugao/rowserrcheck v1.1.0 // indirect
Expand All @@ -92,9 +99,12 @@ require (
github.com/mbilski/exhaustivestruct v1.2.0 // indirect
github.com/mgechev/dots v0.0.0-20190921121421-c36f7dcfbb81 // indirect
github.com/mgechev/revive v1.0.7 // indirect
github.com/mitchellh/copystructure v1.2.0 // indirect
github.com/mitchellh/go-homedir v1.1.0 // indirect
github.com/mitchellh/mapstructure v1.1.2 // indirect
github.com/mitchellh/reflectwalk v1.0.2 // indirect
github.com/moricho/tparallel v0.2.1 // indirect
github.com/mwitkow/go-proto-validators v0.3.2 // indirect
github.com/nakabonne/nestif v0.3.0 // indirect
github.com/nbutton23/zxcvbn-go v0.0.0-20210217022336-fa2cb2858354 // indirect
github.com/nishanths/exhaustive v0.1.0 // indirect
Expand All @@ -110,6 +120,8 @@ require (
github.com/prometheus/client_model v0.2.0 // indirect
github.com/prometheus/common v0.10.0 // indirect
github.com/prometheus/procfs v0.1.3 // indirect
github.com/pseudomuto/protoc-gen-doc v1.5.0 // indirect
github.com/pseudomuto/protokit v0.2.0 // indirect
github.com/quasilyte/go-ruleguard v0.3.4 // indirect
github.com/quasilyte/regex/syntax v0.0.0-20200407221936-30656e2c4a95 // indirect
github.com/ryancurrah/gomodguard v1.2.2 // indirect
Expand All @@ -120,7 +132,7 @@ require (
github.com/sirupsen/logrus v1.8.1 // indirect
github.com/sonatard/noctx v0.0.1 // indirect
github.com/sourcegraph/go-diff v0.6.1 // indirect
github.com/spf13/afero v1.1.2 // indirect
github.com/spf13/afero v1.6.0 // indirect
github.com/spf13/cast v1.3.0 // indirect
github.com/spf13/cobra v1.1.3 // indirect
github.com/spf13/jwalterweatherman v1.0.0 // indirect
Expand All @@ -139,12 +151,13 @@ require (
github.com/ultraware/whitespace v0.0.4 // indirect
github.com/uudashr/gocognit v1.0.1 // indirect
github.com/yeya24/promlinter v0.1.0 // indirect
golang.org/x/mod v0.4.2 // indirect
golang.org/x/sys v0.0.0-20210510120138-977fb7262007 // indirect
golang.org/x/text v0.3.5 // indirect
golang.org/x/tools v0.1.3 // indirect
golang.org/x/crypto v0.0.0-20210921155107-089bfa567519 // indirect
golang.org/x/mod v0.5.0 // indirect
golang.org/x/sys v0.0.0-20210816183151-1e6c022a8912 // indirect
golang.org/x/text v0.3.7 // indirect
golang.org/x/tools v0.1.5 // indirect
golang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1 // indirect
google.golang.org/genproto v0.0.0-20210617175327-b9e0b3197ced // indirect
google.golang.org/genproto v0.0.0-20211101144312-62acf1d99145 // indirect
gopkg.in/ini.v1 v1.51.0 // indirect
gopkg.in/tomb.v1 v1.0.0-20141024135613-dd632973f1e7 // indirect
gopkg.in/yaml.v2 v2.4.0 // indirect
Expand Down
Loading

0 comments on commit 10e2331

Please sign in to comment.