docs: user documentation on github pages (#195)

* docs: user documentation on github pages

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

* GitHub action to build (check) and deploy documentation

* Apply suggestions from code review
* Update proto + readme based on feedback
* Remove ADR from the footer
* Minor doc changes

Co-authored-by: Claudia <[email protected]>
Co-authored-by: Richard Case <[email protected]>

.github/workflows/deploy-docs.yaml

@@ -0,0 +1,45 @@
+name: Documentation
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+jobs:
+  checks:
+    if: github.event_name != 'push'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v1
+      - uses: actions/setup-node@v1
+        with:
+          node-version: '14.x'
+      - uses: actions/setup-go@v2
+        with:
+          go-version: '1.17'
+      - name: Build docs
+        run: make docs-build
+  release:
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v1
+      - uses: actions/setup-node@v1
+        with:
+          node-version: '14.x'
+      - uses: actions/setup-go@v2
+        with:
+          go-version: '1.17'
+      - uses: webfactory/[email protected]
+        with:
+          ssh-private-key: ${{ secrets.FLINTLOCK_DOCS_WEAVEWORKS_DOCS_BOT_DEPLOY_KEY }}
+      - name: Release to GitHub Pages
+        env:
+          USE_SSH: true
+          GIT_USER: git
+          DEPLOYMENT_BRANCH: gh-pages
+        run: |
+          git config --global user.email "[email protected]"
+          git config --global user.name "weaveworks-docs-bot"
+          make docs-deploy

Makefile

@@ -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
@@ -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
@@ -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
 
@@ -174,6 +178,26 @@ $(BUF): $(TOOLS_BIN_DIR) $(BUF_SHARE)
 	cp $(TOOLS_SHARE_DIR)/buf/bin/* $(TOOLS_BIN_DIR)
 	rm -rf $(TOOLS_SHARE_DIR)/buf
 
+##@ Docs
+.PHONY: docs-install
+docs-install:
+	@if [ ! -d "userdocs/node_modules" ]; then \
+		echo " >>> npm install"; \
+		cd ./userdocs && npm install; \
+	fi
+
+.PHONY: docs-build
+docs-build: ## Build userdocs site
+docs-build: generate-proto docs-install
+	cd ./userdocs && yarn build
+
+.PHONY: docs-deploy
+docs-deploy: docs-build
+	cd ./userdocs && \
+		DEPLOYMENT_BRANCH=gh-pages \
+		USE_SSH=true \
+		yarn deploy
+
 ##@ Utility
 
 .PHONY: help

README.md

@@ -17,8 +17,8 @@ Using API requests (via gRPC or HTTP):
 
 - Create, update, delete microVMs using Firecracker
 - Manage the lifecycle of microVMs (i.e. start, stop, pause)
-- Make metadata available to microVMs to support cloud-init, ignition etc
-- Use OCI images for the volumes, kernel & initrd
+- Configure microVM metadata via cloud-init, ignition etc
+- Use OCI images for microVM volumes, kernel and initrd
 - (coming soon) Use CNI to configure the network for the microVMs
 
 ## Documentation

api/types/microvm.proto

@@ -131,7 +131,7 @@ message VolumeSource {
 
 // ContainerVolumeSource represents the details of a volume coming from a OCI image.
 message ContainerVolumeSource {
-    // Image specifies teh conatiner image to use for the volume.
+    // Image specifies the conatiner image to use for the volume.
     string image = 1;
 }
 

buf.gen.yaml

@@ -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

buf.yaml

@@ -17,4 +17,4 @@ lint:
     - PACKAGE_DIRECTORY_MATCH
     - PACKAGE_SAME_DIRECTORY
 breaking:
-  use:
+  use:

docs/adr/0004-merge-create-and-update-plan.md

@@ -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
@@ -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

docs/quick-start.md

@@ -28,12 +28,12 @@ and run: mdtoc -inplace docs/quick-start.md
 
 ## MacOS Users
 
-Flintlock and flintlock tests are only compatible with Linux. We recommend that
+Flintlock is only compatible with Linux. We recommend that
 non-linux users provision a Linux VM in which to work.
 
 You can use Vagrant:
 
-```
+```bash
 vagrant up
 ```
 
@@ -42,14 +42,11 @@ Run the rest of the instructions on this page on that machine.
 
 ## Configure network
 
-If you are using wired connection, you can skip this and jump straight to the
-"Containerd" section. With wireless adapter, macvtap has some issues. The easy
-workaround is to use a bridge and tap devices instead.
+If you are using a wired connection, you can skip this and jump straight to the "Containerd" section.
+
+If you are using a wireless adapter, macvtap cannot be used normally. The workaround is to use a bridge and tap devices instead.
 
-You can use the default kvm network, in this case, skip to "Create and connect
-tap device" and use `default`. We recommend using a dedicated network to avoid
-interference from other kvm machines or processes like IP or MAC address
-conflict.
+You can use the default kvm network, in this case, skip to "Create and connect tap device" and use `default`. However, we recommend using a dedicated network to avoid interference from other kvm machines or processes like IP or MAC address conflict.
 
 ### Install packages and start `libvirtd`
 
@@ -83,15 +80,15 @@ Create the `flintlock.xml` file (feel free to change the IP range):
 
 Define, start and set autostart on the `flintlock` network:
 
-```
+```bash
 sudo virsh net-define flintlock.xml
 sudo virsh net-start flintlock
 sudo virsh net-autostart flintlock
 ```
 
 Now you should see the network in the network list:
 
-```
+```bash
 virsh net-list
  Name       State    Autostart   Persistent
 ---------------------------------------------
@@ -132,7 +129,7 @@ sudo virsh net-dhcp-leases default
 
 [Install ContainerD](https://github.com/containerd/containerd/releases).
 
-_RunC is not required; Flintlock only uses the snapshotter._
+_RunC is not required; Flintlock uses various containerd services only._
 
 ### Create thinpool
 
@@ -268,20 +265,20 @@ There are both GUI and a CLI option.
 
 ### grpc-client-cli
 
-Install the [grpcurl](grpcurl).
+Install [grpcurl][grpcurl].
 
 Use the `./hack/scripts/send.sh` script.
 
 #### Example
 
 To created a MicroVM:
 
-```
+```bash
 ./hack/scripts/send.sh \
   --method CreateMicroVM
 ```
 
-In the terminal where you started the Flintlock server, you should see in the logs that the MircoVM
+In the terminal where you started the Flintlock server (flintlockd), you should see in the logs that the MircoVM
 has started.
 
 ### BloomRPC

hack/tools/go.mod

@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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