Merge pull request #72 from marquiz/backports/docs-0.2

backports: documentation wireframe for release-0.2 branch

.github/workflows/gh-pages.yml

@@ -0,0 +1,30 @@
+name: gh-pages
+on:
+  push:
+    branches:
+      - master
+      - release-*
+    tags:
+      - v[0-9]+.[0-9]+.[0-9]+
+jobs:
+  build:
+    name: Update gh-pages
+    runs-on: ubuntu-latest
+    steps:
+
+    - name: Check out repo
+      uses: actions/checkout@v1
+      with:
+        fetch-depth: 0
+
+    - name: Fetch gh-pages branch
+      run: git fetch --no-tags --prune --depth=1 origin refs/heads/gh-pages:refs/heads/gh-pages
+
+    - name: Build site
+      run: |
+        git config user.name "Github Actions"
+        git config user.email "no-reply@github.com"
+        ./scripts/github/update-gh-pages.sh
+
+    - name: Deploy site
+      run: git push -f https://${GITHUB_ACTOR}:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }} gh-pages

Makefile

@@ -1,6 +1,24 @@
 IMAGE_BUILD_CMD ?= docker build
 IMAGE_BUILD_EXTRA_OPTS ?=
 IMAGE_PUSH_CMD ?= docker push
+CONTAINER_RUN_CMD ?= docker run -u "`id -u`:`id -g`"
+
+MDL ?= mdl
+
+# Docker base command for working with html documentation.
+# Use host networking because 'jekyll serve' is stupid enough to use the
+# same site url than the "host" it binds to. Thus, all the links will be
+# broken if we'd bind to 0.0.0.0
+JEKYLL_VERSION := 3.8
+JEKYLL_ENV ?= development
+SITE_BUILD_CMD := $(CONTAINER_RUN_CMD) --rm -i \
+	-e JEKYLL_ENV=$(JEKYLL_ENV) \
+	--volume="$$PWD/docs:/srv/jekyll":Z \
+	--volume="$$PWD/docs/vendor/bundle:/usr/local/bundle":Z \
+	--network=host jekyll/jekyll:$(JEKYLL_VERSION)
+SITE_BASEURL ?=
+SITE_DESTDIR ?= _site
+JEKYLL_OPTS := -d '$(SITE_DESTDIR)' $(if $(SITE_BASEURL),-b '$(SITE_BASEURL)',)
 
 VERSION := $(shell git describe --tags --dirty --always)
 
@@ -69,6 +87,9 @@ verify-gofmt:
 ci-lint:
 	golangci-lint run --timeout 5m0s
 
+mdlint:
+	find docs/ -path docs/vendor -prune -false -o -name '*.md' | xargs $(MDL) -s docs/mdl-style.rb
+
 clean:
 	go clean
 	rm -f $(BIN)
@@ -88,5 +109,13 @@ push:
 	$(IMAGE_PUSH_CMD) $(IMAGE_TAG)
 	for tag in $(IMAGE_EXTRA_TAGS); do $(IMAGE_PUSH_CMD) $$tag; done
 
+site-build:
+	@mkdir -p docs/vendor/bundle
+	$(SITE_BUILD_CMD) sh -c '/usr/local/bin/bundle install && "$$BUNDLE_BIN/jekyll" build $(JEKYLL_OPTS)'
+
+site-serve:
+	@mkdir -p docs/vendor/bundle
+	$(SITE_BUILD_CMD) sh -c '/usr/local/bin/bundle install && "$$BUNDLE_BIN/jekyll" serve $(JEKYLL_OPTS) -H 127.0.0.1'
+
 .PHONY: all build test generate verify verify-gofmt clean deploy-objects deploy-operator deploy-crds push image
 .SILENT: go_mod

docs/404.html

@@ -0,0 +1,24 @@
+---
+layout: default
+---
+
+<style type="text/css" media="screen">
+  .container {
+    margin: 10px auto;
+    max-width: 600px;
+    text-align: center;
+  }
+  h1 {
+    margin: 30px 0;
+    font-size: 4em;
+    line-height: 1;
+    letter-spacing: -1px;
+  }
+</style>
+
+<div class="container">
+  <h1>404</h1>
+
+  <p><strong>Page not found :(</strong></p>
+  <p>The requested page could not be found.</p>
+</div>

docs/Gemfile

@@ -0,0 +1,29 @@
+source "https://rubygems.org"
+
+# Hello! This is where you manage which Jekyll version is used to run.
+# When you want to use a different version, change it below, save the
+# file and run `bundle install`. Run Jekyll with `bundle exec`, like so:
+#
+#     bundle exec jekyll serve
+#
+# This will help ensure the proper Jekyll version is running.
+# Happy Jekylling!
+gem "jekyll", "~> 3.9.0"
+
+# If you want to use GitHub Pages, remove the "gem "jekyll"" above and
+# uncomment the line below. To upgrade, run `bundle update github-pages`.
+gem "github-pages", "~> 207", group: :jekyll_plugins
+
+# Windows does not include zoneinfo files, so bundle the tzinfo-data gem
+# and associated library.
+install_if -> { RUBY_PLATFORM =~ %r!mingw|mswin|java! } do
+  gem "tzinfo", "~> 1.2"
+  gem "tzinfo-data"
+end
+
+# Performance-booster for watching directories on Windows
+gem "wdm", "~> 0.1.1", :install_if => Gem.win_platform?
+
+# kramdown v2 ships without the gfm parser by default. If you're using
+# kramdown v1, comment out this line.
+#gem "kramdown-parser-gfm"