diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml new file mode 100644 index 00000000..6896ec5c --- /dev/null +++ b/.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 diff --git a/Makefile b/Makefile index 8c3ff388..b5f887c3 100644 --- a/Makefile +++ b/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 diff --git a/docs/404.html b/docs/404.html new file mode 100644 index 00000000..c472b4ea --- /dev/null +++ b/docs/404.html @@ -0,0 +1,24 @@ +--- +layout: default +--- + + + +
+

404

+ +

Page not found :(

+

The requested page could not be found.

+
diff --git a/docs/Gemfile b/docs/Gemfile new file mode 100644 index 00000000..dfbbd46b --- /dev/null +++ b/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" diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock new file mode 100644 index 00000000..86d5ae89 --- /dev/null +++ b/docs/Gemfile.lock @@ -0,0 +1,265 @@ +GEM + remote: https://rubygems.org/ + specs: + activesupport (6.0.3.3) + concurrent-ruby (~> 1.0, >= 1.0.2) + i18n (>= 0.7, < 2) + minitest (~> 5.1) + tzinfo (~> 1.1) + zeitwerk (~> 2.2, >= 2.2.2) + addressable (2.7.0) + public_suffix (>= 2.0.2, < 5.0) + coffee-script (2.4.1) + coffee-script-source + execjs + coffee-script-source (1.11.1) + colorator (1.1.0) + commonmarker (0.17.13) + ruby-enum (~> 0.5) + concurrent-ruby (1.1.7) + dnsruby (1.61.4) + simpleidn (~> 0.1) + em-websocket (0.5.2) + eventmachine (>= 0.12.9) + http_parser.rb (~> 0.6.0) + ethon (0.12.0) + ffi (>= 1.3.0) + eventmachine (1.2.7) + execjs (2.7.0) + faraday (1.0.1) + multipart-post (>= 1.2, < 3) + ffi (1.13.1) + forwardable-extended (2.6.0) + gemoji (3.0.1) + github-pages (207) + github-pages-health-check (= 1.16.1) + jekyll (= 3.9.0) + jekyll-avatar (= 0.7.0) + jekyll-coffeescript (= 1.1.1) + jekyll-commonmark-ghpages (= 0.1.6) + jekyll-default-layout (= 0.1.4) + jekyll-feed (= 0.13.0) + jekyll-gist (= 1.5.0) + jekyll-github-metadata (= 2.13.0) + jekyll-mentions (= 1.5.1) + jekyll-optional-front-matter (= 0.3.2) + jekyll-paginate (= 1.1.0) + jekyll-readme-index (= 0.3.0) + jekyll-redirect-from (= 0.15.0) + jekyll-relative-links (= 0.6.1) + jekyll-remote-theme (= 0.4.1) + jekyll-sass-converter (= 1.5.2) + jekyll-seo-tag (= 2.6.1) + jekyll-sitemap (= 1.4.0) + jekyll-swiss (= 1.0.0) + jekyll-theme-architect (= 0.1.1) + jekyll-theme-cayman (= 0.1.1) + jekyll-theme-dinky (= 0.1.1) + jekyll-theme-hacker (= 0.1.1) + jekyll-theme-leap-day (= 0.1.1) + jekyll-theme-merlot (= 0.1.1) + jekyll-theme-midnight (= 0.1.1) + jekyll-theme-minimal (= 0.1.1) + jekyll-theme-modernist (= 0.1.1) + jekyll-theme-primer (= 0.5.4) + jekyll-theme-slate (= 0.1.1) + jekyll-theme-tactile (= 0.1.1) + jekyll-theme-time-machine (= 0.1.1) + jekyll-titles-from-headings (= 0.5.3) + jemoji (= 0.11.1) + kramdown (= 2.3.0) + kramdown-parser-gfm (= 1.1.0) + liquid (= 4.0.3) + mercenary (~> 0.3) + minima (= 2.5.1) + nokogiri (>= 1.10.4, < 2.0) + rouge (= 3.19.0) + terminal-table (~> 1.4) + github-pages-health-check (1.16.1) + addressable (~> 2.3) + dnsruby (~> 1.60) + octokit (~> 4.0) + public_suffix (~> 3.0) + typhoeus (~> 1.3) + html-pipeline (2.14.0) + activesupport (>= 2) + nokogiri (>= 1.4) + http_parser.rb (0.6.0) + i18n (0.9.5) + concurrent-ruby (~> 1.0) + jekyll (3.9.0) + addressable (~> 2.4) + colorator (~> 1.0) + em-websocket (~> 0.5) + i18n (~> 0.7) + jekyll-sass-converter (~> 1.0) + jekyll-watch (~> 2.0) + kramdown (>= 1.17, < 3) + liquid (~> 4.0) + mercenary (~> 0.3.3) + pathutil (~> 0.9) + rouge (>= 1.7, < 4) + safe_yaml (~> 1.0) + jekyll-avatar (0.7.0) + jekyll (>= 3.0, < 5.0) + jekyll-coffeescript (1.1.1) + coffee-script (~> 2.2) + coffee-script-source (~> 1.11.1) + jekyll-commonmark (1.3.1) + commonmarker (~> 0.14) + jekyll (>= 3.7, < 5.0) + jekyll-commonmark-ghpages (0.1.6) + commonmarker (~> 0.17.6) + jekyll-commonmark (~> 1.2) + rouge (>= 2.0, < 4.0) + jekyll-default-layout (0.1.4) + jekyll (~> 3.0) + jekyll-feed (0.13.0) + jekyll (>= 3.7, < 5.0) + jekyll-gist (1.5.0) + octokit (~> 4.2) + jekyll-github-metadata (2.13.0) + jekyll (>= 3.4, < 5.0) + octokit (~> 4.0, != 4.4.0) + jekyll-mentions (1.5.1) + html-pipeline (~> 2.3) + jekyll (>= 3.7, < 5.0) + jekyll-optional-front-matter (0.3.2) + jekyll (>= 3.0, < 5.0) + jekyll-paginate (1.1.0) + jekyll-readme-index (0.3.0) + jekyll (>= 3.0, < 5.0) + jekyll-redirect-from (0.15.0) + jekyll (>= 3.3, < 5.0) + jekyll-relative-links (0.6.1) + jekyll (>= 3.3, < 5.0) + jekyll-remote-theme (0.4.1) + addressable (~> 2.0) + jekyll (>= 3.5, < 5.0) + rubyzip (>= 1.3.0) + jekyll-sass-converter (1.5.2) + sass (~> 3.4) + jekyll-seo-tag (2.6.1) + jekyll (>= 3.3, < 5.0) + jekyll-sitemap (1.4.0) + jekyll (>= 3.7, < 5.0) + jekyll-swiss (1.0.0) + jekyll-theme-architect (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-cayman (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-dinky (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-hacker (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-leap-day (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-merlot (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-midnight (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-minimal (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-modernist (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-primer (0.5.4) + jekyll (> 3.5, < 5.0) + jekyll-github-metadata (~> 2.9) + jekyll-seo-tag (~> 2.0) + jekyll-theme-slate (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-tactile (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-time-machine (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-titles-from-headings (0.5.3) + jekyll (>= 3.3, < 5.0) + jekyll-watch (2.2.1) + listen (~> 3.0) + jemoji (0.11.1) + gemoji (~> 3.0) + html-pipeline (~> 2.2) + jekyll (>= 3.0, < 5.0) + kramdown (2.3.0) + rexml + kramdown-parser-gfm (1.1.0) + kramdown (~> 2.0) + liquid (4.0.3) + listen (3.2.1) + rb-fsevent (~> 0.10, >= 0.10.3) + rb-inotify (~> 0.9, >= 0.9.10) + mercenary (0.3.6) + mini_portile2 (2.4.0) + minima (2.5.1) + jekyll (>= 3.5, < 5.0) + jekyll-feed (~> 0.9) + jekyll-seo-tag (~> 2.1) + minitest (5.14.2) + multipart-post (2.1.1) + nokogiri (1.10.10) + mini_portile2 (~> 2.4.0) + octokit (4.18.0) + faraday (>= 0.9) + sawyer (~> 0.8.0, >= 0.5.3) + pathutil (0.16.2) + forwardable-extended (~> 2.6) + public_suffix (3.1.1) + rb-fsevent (0.10.4) + rb-inotify (0.10.1) + ffi (~> 1.0) + rexml (3.2.4) + rouge (3.19.0) + ruby-enum (0.8.0) + i18n + rubyzip (2.3.0) + safe_yaml (1.0.5) + sass (3.7.4) + sass-listen (~> 4.0.0) + sass-listen (4.0.0) + rb-fsevent (~> 0.9, >= 0.9.4) + rb-inotify (~> 0.9, >= 0.9.7) + sawyer (0.8.2) + addressable (>= 2.3.5) + faraday (> 0.8, < 2.0) + simpleidn (0.1.1) + unf (~> 0.1.4) + terminal-table (1.8.0) + unicode-display_width (~> 1.1, >= 1.1.1) + thread_safe (0.3.6) + typhoeus (1.4.0) + ethon (>= 0.9.0) + tzinfo (1.2.7) + thread_safe (~> 0.1) + tzinfo-data (1.2020.1) + tzinfo (>= 1.0.0) + unf (0.1.4) + unf_ext + unf_ext (0.0.7.7) + unicode-display_width (1.7.0) + wdm (0.1.1) + zeitwerk (2.4.0) + +PLATFORMS + ruby + +DEPENDENCIES + github-pages (~> 207) + jekyll (~> 3.9.0) + tzinfo (~> 1.2) + tzinfo-data + wdm (~> 0.1.1) + +BUNDLED WITH + 2.0.2 diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 00000000..75fedad5 --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1,54 @@ +# Welcome to Jekyll! +# +# This config file is meant for settings that affect your whole blog, values +# which you are expected to set up once and rarely edit after that. If you find +# yourself editing this file very often, consider using Jekyll's data files +# feature for the data you need to update frequently. +# +# For technical reasons, this file is *NOT* reloaded automatically when you use +# 'bundle exec jekyll serve'. If you change this file, please restart the server process. + +# Site settings +# These are used to personalize your new site. If you look in the HTML files, +# you will see them accessed via {{ site.title }}, {{ site.email }}, and so on. +# You can create any custom variable you would like, and they will be accessible +# in the templates via {{ site.myvariable }}. +title: Node Feature Discovery Operator +description: >- # this means to ignore newlines until "baseurl:" + Documentation of Node Feature Discovery Operator - an operator for managing + detection of hardware features and configuration in a kubernetes cluster. + +url: "https://kubernetes-sigs.github.com" # the base hostname & protocol for your site, e.g. http://example.com + +repository: kubernetes-sigs/node-feature-discovery-operator + +# Build settings +markdown: kramdown +kramdown: + toc_levels: 1..3 + +remote_theme: rundocs/jekyll-rtd-theme@v2.0.9 + +# Exclude from processing. +# The following items will not be processed, by default. Create a custom list +# to override the default setting. +# exclude: +# - Gemfile +# - Gemfile.lock +# - node_modules +# - vendor/bundle/ +# - vendor/cache/ +# - vendor/gems/ +# - vendor/ruby/ + +# Document versioning +version: master +display_version_list: true + +# Release is the full released version number. Used to make external links to +# point to the correct blobs in the Github repo. This is also the version shown +# in the sidebar (top left corner of the page) +release: master + +# Container image which to point to in the documentation +container_image: gcr.io/k8s-staging-nfd/node-feature-discovery-operator:master diff --git a/docs/_includes/class/addons-wrap.liquid b/docs/_includes/class/addons-wrap.liquid new file mode 100644 index 00000000..993d4cb5 --- /dev/null +++ b/docs/_includes/class/addons-wrap.liquid @@ -0,0 +1,58 @@ +
+
+
+ {{ site.title }} +
+
+ + {{ site.version }} + + +
+
+
+ {% if site.display_version_list %} +
+
Versions
+ + {% if jekyll.environment == "development" %} +
+ {{ site.version }} +
+ {% else %} + {% comment %} + Drop the last component from site.baseurl which is supposed to + be pointing to a subdirectory of the true site baseurl. + {% endcomment %} + {% assign spliturl = site.baseurl | split: "/" %} + {% assign last = spliturl.size | minus: 1 %} + {% assign baseurl = spliturl | slice: 0, last | join: "/" %} + + + + {% endif %} +
+ {% endif %} + {%- assign items = "github" | split: ", " -%} + {% for item in items -%} + {% include addons/{{ item }}.liquid %} + {% endfor -%} +
+
+ The + software + is under the terms of + {{ docs.license.name | default: "The Unlicense" }}. +
+
+
diff --git a/docs/_includes/class/sidebar-wrap.liquid b/docs/_includes/class/sidebar-wrap.liquid new file mode 100644 index 00000000..e7fdcce2 --- /dev/null +++ b/docs/_includes/class/sidebar-wrap.liquid @@ -0,0 +1,23 @@ + diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..38c57ba7 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,9 @@ +--- +title: "Introduction" +layout: default +sort: 1 +--- + +# Introduction + +***COMING SOON.*** diff --git a/docs/mdl-style.rb b/docs/mdl-style.rb new file mode 100644 index 00000000..29ff3141 --- /dev/null +++ b/docs/mdl-style.rb @@ -0,0 +1,6 @@ +all +# Exclude MD041 - First line in file should be a top level header +exclude_rule 'MD041' +rule 'MD013', :tables => false +rule 'MD013', :code_blocks => false +rule 'MD024', :allow_different_nesting => true diff --git a/scripts/github/update-gh-pages.sh b/scripts/github/update-gh-pages.sh new file mode 100755 index 00000000..6158bf66 --- /dev/null +++ b/scripts/github/update-gh-pages.sh @@ -0,0 +1,171 @@ +#!/bin/bash -e +set -o pipefail + +this=`basename $0` + +usage () { +cat << EOF +Usage: $this [-h] [-a] [SITE_SUBDIR] + +Options: + -h show this help and exit + -a amend (with --reset-author) instead of creating a new commit + -p REMOTE do git push to remote repo +EOF +} + +# Helper function for detecting available versions from the current directory +create_versions_js() { + local _baseurl="/node-feature-discovery-operator" + + echo -e "function getVersionListItems() {\n return [" + # 'stable' is a symlink pointing to the latest version + [ -f stable ] && echo " { name: 'stable', url: '$_baseurl/stable' }," + for f in `ls -d */ | tr -d /` ; do + echo " { name: '$f', url: '$_baseurl/$f' }," + done + echo -e " ];\n}" +} + +# +# Argument parsing +# +while getopts "hap:" opt; do + case $opt in + h) usage + exit 0 + ;; + a) amend="--amend --reset-author" + ;; + p) push_remote="$OPTARG" + ;; + *) usage + exit 1 + ;; + esac +done +shift "$((OPTIND - 1))" + +site_subdir="$1" + +# Check that no extra args were provided +if [ $# -gt 1 ]; then + echo "ERROR: extra positional arguments: $@" + usage + exit 1 +fi + +# +# Build the documentation +# +build_dir="docs/_site" +echo "Creating new Git worktree at $build_dir" +git worktree add "$build_dir" gh-pages + +# Drop worktree on exit +trap "echo 'Removing Git worktree $build_dir'; git worktree remove '$build_dir'" EXIT + +# Parse subdir name from GITHUB_REF +if [ -z "$site_subdir" ]; then + case "$GITHUB_REF" in + refs/tags/*) + _base_ref=${GITHUB_REF#refs/tags/} + ;; + refs/heads/*) + _base_ref=${GITHUB_REF#refs/heads/} + ;; + *) _base_ref= + esac + echo "Parsed baseref: '$_base_ref'" + + case "$GITHUB_REF" in + refs/tags/v*) + _version=${GITHUB_REF#refs/tags/v} + ;; + refs/heads/release-*) + _version=${GITHUB_REF#refs/heads/release-} + ;; + *) _version= + esac + echo "Detected version: '$_version'" + + _version=`echo -n $_version | sed -nE s'!^([0-9]+\.[0-9]+).*$!\1!p'` + + # User version as the subdir + site_subdir=${_version:+v$_version} + # Fallback to base-ref i.e. name of the branch or tag + site_subdir=${site_subdir:-$_base_ref} +fi + +# Default to 'master' if no subdir was given and we couldn't parse +# it +site_subdir=${site_subdir:-master} + +# Check if this ref is for a released version +if [ "$site_subdir" != "master" ]; then + _base_tag=`git describe --abbrev=0 || :` + case "$_base_tag" in + $site_subdir*) + ;; + *) + echo "Not a released version. Parsed release branch is $site_subdir but based on tag $_base_tag. Stopping here." + echo "SHA `git describe` (`git rev-parse HEAD`)" + exit 0 + ;; + esac +fi + +echo "Updating site subdir: '$site_subdir'" + +export SITE_DESTDIR="_site/$site_subdir" +export SITE_BASEURL="/node-feature-discovery-operator/$site_subdir" +export JEKYLL_ENV=production +make site-build + +# +# Update gh-pages branch +# +if [ -n "$_GIT_TAG" ]; then + commit_hash=${GIT_TAG:10} +else + commit_hash=`git describe --dirty --always` +fi + +# Switch to work in the gh-pages worktree +cd "$build_dir" + +_stable=`(ls -d1 v*/ || :) | sort -n | tail -n1` +if [ -n "$_stable" ]; then + ln -sfT "$_stable" stable + redirect_to=stable +else + redirect_to=$site_subdir +fi + +# Detect existing versions from the gh-pages branch +create_versions_js > versions.js + +cat > index.html << EOF + +EOF + +if [ -z "`git status --short`" ]; then + echo "No new content, gh-pages branch already up-to-date" + exit 0 +fi + +# Create a new commit +commit_msg=`echo -e "Update documentation for $site_subdir\n\nAuto-generated from $commit_hash by '$this'"` + +echo "Committing changes..." +git add . +git commit $amend -m "$commit_msg" + +cd - + +echo "gh-pages branch successfully updated" + +if [ -n "$push_remote" ]; then + echo "Pushing gh-pages to $push_remote" + git push ${amend+-f} "$push_remote" gh-pages +fi diff --git a/scripts/test-infra/build-gh-pages.sh b/scripts/test-infra/build-gh-pages.sh new file mode 100755 index 00000000..5cdd67ec --- /dev/null +++ b/scripts/test-infra/build-gh-pages.sh @@ -0,0 +1,4 @@ +#!/bin/bash -e + +# Build docs +JEKYLL_ENV=production make site-build diff --git a/scripts/test-infra/mdlint.sh b/scripts/test-infra/mdlint.sh new file mode 100755 index 00000000..4b4b16bf --- /dev/null +++ b/scripts/test-infra/mdlint.sh @@ -0,0 +1,7 @@ +#!/bin/bash -e + +# Install mdl +gem install mdl -v 0.11.0 + +# Run verify steps +make mdlint