docs(build): add Makefile, Dockerfile, scripts; bump Hugo to 0.74.3; add build targets to netlify.toml

Dockerfile

@@ -1,15 +1,35 @@
-FROM jekyll/jekyll:3.8
+# Modified from github.com/kubernetes/website/Dockerfile
+# Credit to Julien Guyomard (https://github.com/jguyomard). This Dockerfile
+# is essentially based on his Dockerfile at
+# https://github.com/jguyomard/docker-hugo/blob/master/Dockerfile. The only significant
+# change is that the Hugo version is now an overridable argument rather than a fixed
+# environment variable.
 
-EXPOSE 4000
+FROM alpine:latest
 
-# USER jekyll
+LABEL maintainer="Armory Docs Team <[email protected]>"
 
-RUN gem install bundler
+RUN apk add --no-cache \
+    curl \
+    git \
+    openssh-client \
+    rsync \
+    build-base \
+    libc6-compat \
+    npm && \
+    npm install -G autoprefixer postcss-cli
 
-WORKDIR /srv/jekyll
+ARG HUGO_VERSION
 
-COPY Gemfile* /srv/jekyll/
+RUN mkdir -p /usr/local/src && \
+    cd /usr/local/src && \
+    curl -L https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_Linux-64bit.tar.gz | tar -xz && \
+    mv hugo /usr/local/bin/hugo && \
+    addgroup -Sg 1000 hugo && \
+    adduser -Sg hugo -u 1000 -h /src hugo
 
-RUN touch Gemfile.lock \
-  && chmod a+w Gemfile.lock \
-  && bundle install
+WORKDIR /src
+
+USER hugo:hugo
+
+EXPOSE 1313

Makefile

@@ -0,0 +1,61 @@
+## stolen from kuberntes/website
+HUGO_VERSION      = $(shell grep ^HUGO_VERSION netlify.toml | tail -n 1 | cut -d '=' -f 2 | tr -d " \"\n")
+NODE_BIN          = node_modules/.bin
+NETLIFY_FUNC      = $(NODE_BIN)/netlify-lambda
+
+# The CONTAINER_ENGINE variable is used for specifying the container engine. By default 'docker' is used
+# but this can be overridden when calling make, e.g.
+# CONTAINER_ENGINE=podman make container-image
+CONTAINER_ENGINE ?= docker
+IMAGE_VERSION=$(shell scripts/hash-files.sh Dockerfile Makefile | cut -c 1-12)
+CONTAINER_IMAGE   = armorydocs-hugo:v$(HUGO_VERSION)-$(IMAGE_VERSION)
+CONTAINER_RUN     = $(CONTAINER_ENGINE) run --rm --interactive --tty --volume $(CURDIR):/src
+
+CCRED=\033[0;31m
+CCEND=\033[0m
+
+.PHONY: all build build-preview help serve
+
+help: ## Show this help.
+	@awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z_-]+:.*?## / {sub("\\\\n",sprintf("\n%22c"," "), $$2);printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST)
+
+module-check:
+	@git submodule status --recursive | awk '/^[+-]/ {printf "\033[31mWARNING\033[0m Submodule not initialized: \033[34m%s\033[0m\n",$$2}' 1>&2
+
+all: build ## Build site with production settings and put deliverables in ./public
+
+build: module-check ## Build site with production settings and put deliverables in ./public
+	hugo --minify
+
+build-preview: module-check ## Build site with drafts and future posts enabled
+	hugo --buildDrafts --buildFuture
+
+deploy-preview: ## Deploy preview site via netlify
+	hugo --enableGitInfo --buildFuture --buildDrafts -b $(DEPLOY_PRIME_URL)
+
+functions-build:
+	$(NETLIFY_FUNC) build functions-src
+
+check-headers-file:
+	scripts/check-headers-file.sh
+
+production-build: build check-headers-file ## Build the production site and ensure that noindex headers aren't added
+
+non-production-build: ## Build the non-production site, which adds noindex headers to prevent indexing
+	hugo --enableGitInfo
+
+serve: module-check ## Boot the development server.
+	hugo server --buildFuture --buildDrafts
+
+container-image:
+	$(CONTAINER_ENGINE) build . \
+		--network=host \
+		--tag $(CONTAINER_IMAGE) \
+		--build-arg HUGO_VERSION=$(HUGO_VERSION)
+
+container-build: module-check
+	$(CONTAINER_RUN) $(CONTAINER_IMAGE) hugo --minify
+
+container-serve: module-check
+	$(CONTAINER_RUN) --mount type=tmpfs,destination=/src/resources,tmpfs-mode=0777 -p 1313:1313 $(CONTAINER_IMAGE) hugo server --buildFuture --buildDrafts --bind 0.0.0.0
+

README.md

@@ -1,14 +1,23 @@
+[![Netlify Status](https://api.netlify.com/api/v1/badges/d0be032e-c23d-48e5-8fbc-f7d5f2388fce/deploy-status)](https://app.netlify.com/sites/armory-docs/deploys)
+
 # Overview
 
 This is the repo for Armory documentation (https://docs.armory.io). We welcome contributions from people outside of Armory.
 
-The site is hosted by [Netlify](https://www.netlify.com/), which generates a preview build for every pull request. Install [Hugo](https://gohugo.io/) if you want to compile and run the project locally. The Hugo extended version is specified in `netlify.toml` (currently 0.71.1).
-
 The latest version of the docs website is the `master` branch. Previous releases point to branches that start with `release-`.
 
-## Cloning the project
+## Prerequisites
+
+The site is hosted by [Netlify](https://www.netlify.com/), which generates a preview build for every pull request. Install the following if you want to compile and run the project locally. Make sure to install the Hugo extended version specified by the `HUGO_VERSION` environment variable in the [`netlify.toml`](netlify.toml#L14) file.
+
+- [yarn](https://yarnpkg.com/)
+- [npm](https://www.npmjs.com/)
+- [Go](https://golang.org/)
+- [Hugo](https://gohugo.io/)
+- A container runtime, like [Docker](https://www.docker.com/).
 
-If you work for Armory, see the internal docs for how to contribute content.
+
+## Cloning the project
 
 People who are not part of the Armory organization need to create a fork of this repo. See the GitHub.com help [docs](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-forks) for how to fork a repo.
 
@@ -18,10 +27,11 @@ Clone your forked repo:
 git clone [email protected]:<github-username>/docs.git
 ```
 
-Armory docs uses the [Docsy]() theme as a submodule. You have to update the submodule if you want to build locally.
+Armory docs uses the [Docsy Hugo theme](https://github.com/google/docsy#readme) theme as a submodule. You have to update the submodule if you want to build locally. Even if you plan to run the website in a container, we strongly recommend pulling in the submodule and other development dependencies by running the following:
 
 ```bash
 cd docs
+yarn # install Yarn depend
 git submodule update --init --recursive
 ```
 
@@ -86,11 +96,65 @@ Content is in `content/en/docs`. Make your changes to the desired file.
 
 Use the `git status` command at any time to see what files you've changed.
 
-If you have installed [Hugo](https://gohugo.io/getting-started/installing/) and want to preview your changes locally, run from the repo root:
+## Running the website locally
+
+### Using a container
+
+To build the site in a container, run the following to build the container image and run it:
+
+```
+make container-image
+make container-serve
+```
+
+Open up your browser to http://localhost:1313 to view the website. As you make changes to the source files, Hugo updates the website and forces a browser refresh.
+
+### Using Hugo
+
+To build and test the site locally, run:
+
+```bash
+make serve
+```
+
+This will start the local Hugo server on port 1313. Open up your browser to http://localhost:1313 to view the website. As you make changes to the source files, Hugo updates the website and forces a browser refresh.
+
+### Troubleshooting macOS for too many open files
 
+If you run `make serve` on macOS and receive the following error:
+
+```
+ERROR 2020/08/01 19:09:18 Error: listen tcp 127.0.0.1:1313: socket: too many open files
+make: *** [serve] Error 1
 ```
-hugo server
+
+Try checking the current limit for open files:
+
+`launchctl limit maxfiles`
+
+Then run the following commands (adapted from https://gist.github.com/tombigel/d503800a282fcadbee14b537735d202c):
+
 ```
+#!/bin/sh
+
+# These are the original gist links, linking to my gists now.
+# curl -O https://gist.githubusercontent.com/a2ikm/761c2ab02b7b3935679e55af5d81786a/raw/ab644cb92f216c019a2f032bbf25e258b01d87f9/limit.maxfiles.plist
+# curl -O https://gist.githubusercontent.com/a2ikm/761c2ab02b7b3935679e55af5d81786a/raw/ab644cb92f216c019a2f032bbf25e258b01d87f9/limit.maxproc.plist
+
+curl -O https://gist.githubusercontent.com/tombigel/d503800a282fcadbee14b537735d202c/raw/ed73cacf82906fdde59976a0c8248cce8b44f906/limit.maxfiles.plist
+curl -O https://gist.githubusercontent.com/tombigel/d503800a282fcadbee14b537735d202c/raw/ed73cacf82906fdde59976a0c8248cce8b44f906/limit.maxproc.plist
+
+sudo mv limit.maxfiles.plist /Library/LaunchDaemons
+sudo mv limit.maxproc.plist /Library/LaunchDaemons
+
+sudo chown root:wheel /Library/LaunchDaemons/limit.maxfiles.plist
+sudo chown root:wheel /Library/LaunchDaemons/limit.maxproc.plist
+
+sudo launchctl load -w /Library/LaunchDaemons/limit.maxfiles.plist
+```
+
+This works for Catalina as well as Mojave macOS.
+
 
 ## Commit your changes
 

content/en/docs/smoke-test.md

@@ -3,14 +3,10 @@ title: "Smoke Test"
 linkTitle: "Smoke Test"
 weight: 999
 draft: true
-description: >
-  Markdown stuff - change to draft before publication
 ---
 
 
-Images links to test link checker
-
-![Architecture Diagram](/images/install_admin_guides_SpinnakerArchitecture.png)
+>THIS IS A DRAFT AND SHOULD ONLY APPEAR IN LOCAL BUILDS AND DEPLOY PREVIEWS
 
 
 {{% pageinfo %}}

netlify.toml

@@ -1,16 +1,38 @@
 # Hugo build configuration for Netlify
 # (https://gohugo.io/hosting-and-deployment/hosting-on-netlify/#configure-hugo-version-in-netlify)
 # Default build settings
-[build]
-  publish = "public"
-  command = "cd themes/docsy && git submodule update -f --init && cd ../.. && hugo"
 
+[build]
+# This default build command adds the robots noindex directive to the site headers.
+# It is turned off for only for the production site by using [context.master] below
+# DO NOT REMOVE THIS
+publish = "public"
+functions = "functions"
+command = "git submodule update --init --recursive --depth 1 && make non-production-build"
 
-# "production" environment specific build settings
 [build.environment]
-  HUGO_VERSION = "0.71.1"
-  HUGO_THEME = "docsy"
-  HUGO_ENV = "production"
+HUGO_VERSION = "0.74.3"
+NODE_VERSION= "10.20.0"
+RUBY_VERSION = "2.7.1"
+HUGO_THEME = "docsy"
+
+[context.production.environment]
+HUGO_BASEURL = "https://docs.armory.io/"
+HUGO_ENV = "production"
+HUGO_ENABLEGITINFO = "true"
+
+[context.deploy-preview]
+command = "git submodule update --init --recursive --depth 1 && make deploy-preview"
+
+[context.branch-deploy]
+command = "git submodule update --init --recursive --depth 1 && make deploy-preview"
+
+[context.master]
+# This context is triggered by the `master` branch and allows search indexing
+# DO NOT REMOVE THIS (contact @kubernetes/sig-docs-leads)
+publish = "public"
+command = "git submodule update --init --recursive --depth 1 && make production-build"
+
 
 # section redirects
 [[redirects]]

scripts/README.md

@@ -0,0 +1,92 @@
+# Development scripts for Armory documentation
+
+Modified from github.com/kubernetes/website
+
+| Script                  | Description                                                                                                                           |
+|-------------------------|---------------------------------------------------------------------------------------------------------------------------------------|
+| `find_pr.py`            | Find what GitHub pull requests touch a given file.                                                                                    |
+| `upstream_changes.py`   | Find what changes occurred between two versions.                                                                                      |
+| `test_examples.sh`      | This script tests whether a change affects example files bundled in the website.                                                      |
+| `check-headers-file.sh` | This script checks the headers if you are in a production environment.                                                                |
+| `diff_l10n_branches.py` | This script generates a report of outdated contents in `content/<l10n-lang>` directory by comparing two l10n team milestone branches. |
+
+
+
+## Requirements
+
+Some of those scripts have external requirements. You can install them with the following commands:
+
+```
+python3 -m pip install -r requirements.txt
+```
+
+## find_pr.py
+
+```
+$ ./find_pr.py --help
+Usage: find_pr.py [OPTIONS] PATH
+
+  Find what GitHub pull requests touch a given file.
+
+  ex: ./find_pr.py --tags "language/fr" "content/fr/_index.html"
+
+Options:
+  --tags TEXT          Tags of PullRequest (Can be passed multiple times)
+  --token TEXT         GitHub API token. (Default env variable GITHUB_TOKEN)
+  --last-n-pr INTEGER  Last n-th PullRequests
+  --help               Show this message and exit.
+```
+
+## upstream_changes.py
+
+```
+$ ./upstream_changes.py --help
+Usage: upstream_changes.py [OPTIONS] PATH
+
+  Find what changes occurred between two versions
+
+  ex: ./upstream_changes.py content/fr/_index.html
+
+Options:
+  --reference TEXT  Specify the reference version of the file. Default to the
+                    English one.
+  --git-path TEXT   Specify git path
+  --help            Show this message and exit.
+```
+
+## test_examples.sh
+
+This script tests whether a change affects example files bundled in the website.
+
+To install the dependencies:
+
+    $ ./scripts/test_examples.sh install
+
+To run the examples:
+
+    $ ./scripts/test_examples.sh run
+
+## check-headers-file.sh
+
+This script checks the headers if you are in a production environment.
+
+    ./scripts/check-headers-file.sh
+
+## diff_l10n_branches.py
+
+```
+$ scripts/diff_l10n_branches.py --help
+Usage: diff_l10n_branches.py [OPTIONS] L10N_LANG L_COMMIT R_COMMIT
+
+  This script generates a report of outdated contents in `content/<l10n-
+  lang>` directory by comparing two l10n team milestone branches.
+
+  L10n team owners can open a GitHub issue with the report generated by this
+  script when they start a new team milestone.
+
+  ex: `scripts/diff_l10n_branches.py ko dev-1.15-ko.3 dev-1.15-ko.4`
+
+Options:
+  --src-lang TEXT  Source language
+  --help           Show this message and exit.
+```

scripts/check-headers-file.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+
+if [ "$HUGO_ENV" == "production" ]; then
+  echo "INFO: Production environment. Checking the _headers file for noindex headers."
+
+  if grep -q "noindex" public/_headers; then
+    echo "PANIC: noindex headers were found in the _headers file. This build has failed."
+    exit 1
+  else
+    echo "INFO: noindex headers were not found in the _headers file. All clear."
+    exit 0
+  fi
+else
+  echo "Non-production environment. Skipping the _headers file check."
+  exit 0
+fi