Run brodocs using bazel

Signed-off-by: James Munnelly <james@munnelly.eu>
2018-09-11 11:20:32 +01:00 · 2018-09-11 11:20:32 +01:00 · 5e16dd47ab
commit 5e16dd47ab
parent 38078cf5cd
11 changed files with 475 additions and 101 deletions
--- a/148
+++ b/148
@ -30,6 +30,7 @@ http_archive(
 load(
    "@bazel_gazelle//:deps.bzl",
    "gazelle_dependencies",
+    "go_repository",
 )

 gazelle_dependencies()
@ -133,3 +134,150 @@ http_file(
    sha256 = "287b08291e14f1fae8ba44374b26a2b12eb941af3497ed0ca649253e21ba2f83",
    urls = ["https://github.com/golang/dep/releases/download/v0.5.0/dep-linux-amd64"],
 )
+
+## Brodocs and associated dependencies
+new_git_repository(
+    name = "brodocs",
+    remote = "https://github.com/munnerz/brodocs.git",
+    # We use this specific revision as it contains changes that allow us to
+    # specify custom paths when building documentation.
+    commit = "94937a75f3fd680df04a2cfb06ea7299aad156e9",
+    build_file_content = """
+filegroup(
+    name = "all-srcs",
+    srcs = glob(["**/*"]),
+    visibility = ["//visibility:public"],
+)
+""",
+)
+
+# Setup npm for brodocs doc generation
+git_repository(
+    name = "build_bazel_rules_nodejs",
+    remote = "https://github.com/bazelbuild/rules_nodejs.git",
+    tag = "0.11.5",  # check for the latest tag when you install
+)
+
+load("@build_bazel_rules_nodejs//:package.bzl", "rules_nodejs_dependencies")
+
+rules_nodejs_dependencies()
+
+load("@build_bazel_rules_nodejs//:defs.bzl", "node_repositories")
+
+# TODO: do we need to specify this package.json in node_repositories as well as
+# in npm_install?
+node_repositories(package_json = ["@brodocs//:package.json"])
+
+load("@build_bazel_rules_nodejs//:defs.bzl", "npm_install")
+
+npm_install(
+    name = "brodocs_modules",
+    package_json = "@brodocs//:package.json",
+    package_lock_json = "//hack/brodocs:package-lock.json",
+)
+
+# Load kubernetes-incubator/reference-docs, to be used as part of the docs
+# generation pipeline.
+# This involves quite a few dependencies, hence the long list of go_repository
+# rules.
+# We include them here instead of in Gopkg.{toml,lock} to save extra sources in
+# the repository.
+# These were all taken from the HEAD of each repositories 'master' branch.
+go_repository(
+    name = "io_kubernetes_incubator_reference_docs",
+    # Points to HEAD of the 'kubebuilder' branch
+    commit = "1959039a016c77efe6786b19f3f55f7b3042604f",
+    importpath = "github.com/kubernetes-incubator/reference-docs",
+)
+
+go_repository(
+    name = "in_gopkg_yaml_v2",
+    commit = "5420a8b6744d3b0345ab293f6fcba19c978f1183",
+    remote = "https://github.com/go-yaml/yaml",
+    vcs = "git",
+    importpath = "gopkg.in/yaml.v2",
+)
+
+go_repository(
+    name = "com_github_go_openapi_spec",
+    commit = "f1468acb3b29cdd5c5f6fa29435d2d2d6e6c9ff1",
+    importpath = "github.com/go-openapi/spec",
+)
+
+go_repository(
+    name = "com_github_go_openapi_loads",
+    commit = "fd899182a268dcf25de088722375311d9dee2662",
+    importpath = "github.com/go-openapi/loads",
+)
+
+go_repository(
+    name = "com_github_go_openapi_swag",
+    commit = "dd0dad036e67ae93c27dc64337b3f76296f3a5f0",
+    importpath = "github.com/go-openapi/swag",
+)
+
+go_repository(
+    name = "com_github_go_openapi_analysis",
+    commit = "b006789cd277d4fa4d16767046d694a256c6a218",
+    importpath = "github.com/go-openapi/analysis",
+)
+
+go_repository(
+    name = "com_github_go_openapi_jsonreference",
+    commit = "1c6a3fa339f2743b7b0fd2b842fc455eca2fa9eb",
+    importpath = "github.com/go-openapi/jsonreference",
+)
+
+go_repository(
+    name = "com_github_go_openapi_jsonpointer",
+    commit = "52eb3d4b47c6a51ce2693c8e614a15a07c1af435",
+    importpath = "github.com/go-openapi/jsonpointer",
+)
+
+go_repository(
+    name = "com_github_go_openapi_strfmt",
+    commit = "776114108ccc228238641096ea5be3d24842d4ea",
+    importpath = "github.com/go-openapi/strfmt",
+)
+
+go_repository(
+    name = "com_github_go_openapi_errors",
+    commit = "87bb653288778f8b0d922c5c3fb8b3f00a47ff28",
+    importpath = "github.com/go-openapi/errors",
+)
+
+go_repository(
+    name = "com_github_mailru_easyjson",
+    commit = "60711f1a8329503b04e1c88535f419d0bb440bff",
+    importpath = "github.com/mailru/easyjson",
+)
+
+go_repository(
+    name = "com_github_puerkitobio_purell",
+    commit = "975f53781597ed779763b7b65566e74c4004d8de",
+    importpath = "github.com/PuerkitoBio/purell",
+)
+
+go_repository(
+    name = "com_github_puerkitobio_urlesc",
+    commit = "de5bf2ad457846296e2031421a34e2568e304e35",
+    importpath = "github.com/PuerkitoBio/urlesc",
+)
+
+go_repository(
+    name = "com_github_globalsign_mgo",
+    commit = "1ca0a4f7cbcbe61c005d1bd43fdd8bb8b71df6bc",
+    importpath = "github.com/globalsign/mgo",
+)
+
+go_repository(
+    name = "com_github_mitchellh_mapstructure",
+    commit = "fa473d140ef3c6adf42d6b391fe76707f1f243c8",
+    importpath = "github.com/mitchellh/mapstructure",
+)
+
+go_repository(
+    name = "com_github_asaskevich_govalidator",
+    commit = "f9ffefc3facfbe0caee3fea233cbb6e8208f4541",
+    importpath = "github.com/asaskevich/govalidator",
+)
--- a/docs/generated/reference/BUILD.bazel
+++ b/docs/generated/reference/BUILD.bazel
@ -32,6 +32,7 @@ filegroup(
    srcs = [
        ":package-srcs",
        "//docs/generated/reference/openapi:all-srcs",
+        "//docs/generated/reference/swagger-gen:all-srcs",
    ],
    tags = ["automanaged"],
    visibility = ["//visibility:public"],
--- a/docs/generated/reference/swagger-gen/BUILD.bazel
+++ b/docs/generated/reference/swagger-gen/BUILD.bazel
@ -0,0 +1,37 @@
+load("@io_bazel_rules_go//go:def.bzl", "go_binary", "go_library")
+
+exports_files(["config.yaml"])
+
+go_library(
+    name = "go_default_library",
+    srcs = ["main.go"],
+    importpath = "github.com/jetstack/cert-manager/docs/generated/reference/swagger-gen",
+    tags = ["manual"],
+    visibility = ["//visibility:private"],
+    deps = [
+        "//docs/generated/reference/openapi:go_default_library",
+        "//vendor/github.com/go-openapi/spec:go_default_library",
+        "//vendor/k8s.io/kube-openapi/pkg/common:go_default_library",
+    ],
+)
+
+filegroup(
+    name = "package-srcs",
+    srcs = glob(["**"]),
+    tags = ["automanaged"],
+    visibility = ["//visibility:private"],
+)
+
+filegroup(
+    name = "all-srcs",
+    srcs = [":package-srcs"],
+    tags = ["automanaged"],
+    visibility = ["//visibility:public"],
+)
+
+go_binary(
+    name = "swagger-gen",
+    embed = [":go_default_library"],
+    tags = ["manual"],
+    visibility = ["//visibility:public"],
+)
--- a/docs/generated/reference/swagger-gen/main.go
+++ b/docs/generated/reference/swagger-gen/main.go
@ -0,0 +1,60 @@
+/*
+Copyright 2018 The Jetstack cert-manager contributors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"log"
+	"os"
+	"strings"
+
+	"github.com/go-openapi/spec"
+	"k8s.io/kube-openapi/pkg/common"
+
+	"github.com/jetstack/cert-manager/docs/generated/reference/openapi"
+)
+
+func main() {
+	WriteOpenAPI(openapi.GetOpenAPIDefinitions)
+}
+
+// WriteOpenAPI writes the openapi json to docs/reference/openapi-spec/swagger.json
+func WriteOpenAPI(openapi func(ref common.ReferenceCallback) map[string]common.OpenAPIDefinition) {
+	defs := openapi(func(name string) spec.Ref {
+		parts := strings.Split(name, "/")
+		return spec.MustCreateRef(fmt.Sprintf("#/definitions/%s.%s",
+			common.EscapeJsonPointer(parts[len(parts)-2]),
+			common.EscapeJsonPointer(parts[len(parts)-1])))
+	})
+
+	o, err := json.MarshalIndent(defs, "", "    ")
+	if err != nil {
+		log.Fatalf("Could not Marshal JSON %v\n%v", err, defs)
+	}
+
+	// wd, err := os.Getwd()
+	// if err != nil {
+	// 	log.Fatalf("Error getting working directory: %v", err)
+	// }
+
+	_, err = os.Stdout.Write(o)
+	// err = ioutil.WriteFile(filepath.Join(wd, "docs", "generated", "reference", "openapi-spec", "swagger.json"), o, 0700)
+	if err != nil {
+		log.Fatalf("%v", err)
+	}
+}
--- a/hack/BUILD.bazel
+++ b/hack/BUILD.bazel
@ -113,6 +113,33 @@ sh_test(
    ],
 )

+# Reference docs generation rules
+
+sh_binary(
+    name = "update-reference-docs",
+    srcs = ["update-reference-docs.sh"],
+    data = [
+        "//hack/bin:gen-apidocs",
+        "//hack/bin:swagger-gen",
+        "//hack/brodocs",
+    ],
+    deps = [
+        "@bazel_tools//tools/bash/runfiles",
+    ],
+)
+
+sh_test(
+    name = "verify-reference-docs",
+    srcs = ["verify-reference-docs.sh"],
+    data = [
+        ":update-reference-docs",
+        "//:all-srcs",
+    ],
+    deps = [
+        "@bazel_tools//tools/bash/runfiles",
+    ],
+)
+
 filegroup(
    name = "package-srcs",
    srcs = glob(["**"]),
@ -126,6 +153,7 @@ filegroup(
        ":package-srcs",
        "//hack/bin:all-srcs",
        "//hack/boilerplate:all-srcs",
+        "//hack/brodocs:all-srcs",
        "//hack/deploy:all-srcs",
    ],
    tags = ["automanaged"],
--- a/hack/bin/BUILD.bazel
+++ b/hack/bin/BUILD.bazel
@ -47,6 +47,24 @@ genrule(
    visibility = ["//visibility:public"],
 )

+# We include these rules here to make PATH mapping easier, and to provide a
+# stable arch-independent target for generating swagger.json & apidocs.
+genrule(
+    name = "fetch_swagger-gen",
+    srcs = ["//docs/generated/reference/swagger-gen"],
+    outs = ["swagger-gen"],
+    cmd = "cp $(SRCS) $@",
+    visibility = ["//visibility:public"],
+)
+
+genrule(
+    name = "fetch_gen-apidocs",
+    srcs = ["@io_kubernetes_incubator_reference_docs//gen-apidocs"],
+    outs = ["gen-apidocs"],
+    cmd = "cp $(SRCS) $@",
+    visibility = ["//visibility:public"],
+)
+
 config_setting(
    name = "k8",
    values = {"host_cpu": "k8"},
--- a/hack/brodocs/BUILD.bazel
+++ b/hack/brodocs/BUILD.bazel
@ -0,0 +1,27 @@
+load("@build_bazel_rules_nodejs//:defs.bzl", "nodejs_binary")
+
+nodejs_binary(
+    name = "brodocs",
+    data = [
+        "//docs/generated/reference:all-srcs",
+        "@brodocs//:all-srcs",
+    ],
+    entry_point = "brodocs/brodoc",
+    # Ordinarily this defaults to //:node_modules
+    node_modules = "@brodocs_modules//:node_modules",
+    visibility = ["//visibility:public"],
+)
+
+filegroup(
+    name = "package-srcs",
+    srcs = glob(["**"]),
+    tags = ["automanaged"],
+    visibility = ["//visibility:private"],
+)
+
+filegroup(
+    name = "all-srcs",
+    srcs = [":package-srcs"],
+    tags = ["automanaged"],
+    visibility = ["//visibility:public"],
+)
--- a/hack/brodocs/package-lock.json
+++ b/hack/brodocs/package-lock.json
@ -0,0 +1,88 @@
+{
+  "name": "brodocs",
+  "version": "1.0.0",
+  "lockfileVersion": 1,
+  "requires": true,
+  "dependencies": {
+    "bootstrap": {
+      "version": "3.3.7",
+      "resolved": "https://registry.npmjs.org/bootstrap/-/bootstrap-3.3.7.tgz",
+      "integrity": "sha1-WjiTlFSfIzMIdaOxUGVldPip63E="
+    },
+    "colors": {
+      "version": "1.3.1",
+      "resolved": "https://registry.npmjs.org/colors/-/colors-1.3.1.tgz",
+      "integrity": "sha512-jg/vxRmv430jixZrC+La5kMbUWqIg32/JsYNZb94+JEmzceYbWKTsv1OuTp+7EaqiaWRR2tPcykibwCRgclIsw=="
+    },
+    "ejs": {
+      "version": "2.6.1",
+      "resolved": "https://registry.npmjs.org/ejs/-/ejs-2.6.1.tgz",
+      "integrity": "sha512-0xy4A/twfrRCnkhfk8ErDi5DqdAsAqeGxht4xkCUrsvhhbQNs7E+4jV0CN7+NKIY0aHE72+XvqtBIXzD31ZbXQ==",
+      "dev": true
+    },
+    "font-awesome": {
+      "version": "4.7.0",
+      "resolved": "https://registry.npmjs.org/font-awesome/-/font-awesome-4.7.0.tgz",
+      "integrity": "sha1-j6jPBBGhoxr9B7BtKQK7n8gVoTM="
+    },
+    "highlight.js": {
+      "version": "9.12.0",
+      "resolved": "https://registry.npmjs.org/highlight.js/-/highlight.js-9.12.0.tgz",
+      "integrity": "sha1-5tnb5Xy+/mB1HwKvM2GVhwyQwB4=",
+      "dev": true
+    },
+    "jquery": {
+      "version": "3.3.1",
+      "resolved": "https://registry.npmjs.org/jquery/-/jquery-3.3.1.tgz",
+      "integrity": "sha512-Ubldcmxp5np52/ENotGxlLe6aGMvmF4R8S6tZjsP6Knsaxd/xp3Zrh50cG93lR6nPXyUFwzN3ZSOQI0wRJNdGg=="
+    },
+    "jquery.scrollto": {
+      "version": "2.1.2",
+      "resolved": "https://registry.npmjs.org/jquery.scrollto/-/jquery.scrollto-2.1.2.tgz",
+      "integrity": "sha1-51gNnHrEbvW7JTGUg/b0VxP9fGw=",
+      "requires": {
+        "jquery": "3.3.1"
+      }
+    },
+    "marked": {
+      "version": "0.3.19",
+      "resolved": "https://registry.npmjs.org/marked/-/marked-0.3.19.tgz",
+      "integrity": "sha512-ea2eGWOqNxPcXv8dyERdSr/6FmzvWwzjMxpfGB/sbMccXoct+xY+YukPD+QTUZwyvK7BZwcr4m21WBOW41pAkg==",
+      "dev": true
+    },
+    "mime": {
+      "version": "1.6.0",
+      "resolved": "https://registry.npmjs.org/mime/-/mime-1.6.0.tgz",
+      "integrity": "sha512-x0Vn8spI+wuJ1O6S7gnbaQg8Pxh4NNHb7KSINmEWKiPE4RKOplvijn+NkmYmmRgP68mc70j2EbeTFRsrswaQeg=="
+    },
+    "minimist": {
+      "version": "0.0.10",
+      "resolved": "https://registry.npmjs.org/minimist/-/minimist-0.0.10.tgz",
+      "integrity": "sha1-3j+YVD2/lggr5IrRoMfNqDYwHc8="
+    },
+    "node-static": {
+      "version": "0.7.10",
+      "resolved": "https://registry.npmjs.org/node-static/-/node-static-0.7.10.tgz",
+      "integrity": "sha512-bd7zO5hvCWzdglgwz9t82T4mYTEUzEG5pXnSqEzitvmEacusbhl8/VwuCbMaYR9g2PNK5191yBtAEQLJEmQh1A==",
+      "requires": {
+        "colors": "1.3.1",
+        "mime": "1.6.0",
+        "optimist": "0.6.1"
+      }
+    },
+    "optimist": {
+      "version": "0.6.1",
+      "resolved": "https://registry.npmjs.org/optimist/-/optimist-0.6.1.tgz",
+      "integrity": "sha1-2j6nRob6IaGaERwybpDrFaAZZoY=",
+      "requires": {
+        "minimist": "0.0.10",
+        "wordwrap": "0.0.3"
+      }
+    },
+    "wordwrap": {
+      "version": "0.0.3",
+      "resolved": "https://registry.npmjs.org/wordwrap/-/wordwrap-0.0.3.tgz",
+      "integrity": "sha1-o9XabNXAvAAI03I0u68b7WMFkQc="
+    }
+  }
+}
--- a/hack/update-reference-docs-dockerized.sh
+++ b/hack/update-reference-docs-dockerized.sh
@ -1,30 +0,0 @@
-#!/bin/bash
-
-# Copyright 2018 The Jetstack cert-manager contributors.
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-set -o errexit
-set -o nounset
-set -o pipefail
-
-REPO_ROOT=$(git rev-parse --show-toplevel)
-
-IMAGE="${IMAGE:-munnerz/gen-apidocs-img}"
-IMAGE_TAG="${IMAGE_TAG:-0.1}"
-
-docker run \
-    -v "${REPO_ROOT}:/go/src/github.com/jetstack/cert-manager" \
-    --workdir "/go/src/github.com/jetstack/cert-manager" \
-    "${IMAGE}:${IMAGE_TAG}" \
-    ./hack/update-reference-docs.sh
--- a/hack/update-reference-docs.sh
+++ b/hack/update-reference-docs.sh
@ -18,17 +18,14 @@ set -o errexit
 set -o nounset
 set -o pipefail

-## This script will generate a reference documentation site into ./docs/generated/reference/reference/api-docs
-## It requires a number of tools be installed:
-##
-## * openapi-gen
-## * gen-apidocs
-##
-
-SCRIPT_ROOT=$(dirname "${BASH_SOURCE}")/..
+# This script should be run via `bazel run //hack:update-reference-docs`
+REPO_ROOT=${BUILD_WORKSPACE_DIRECTORY:-"$(cd "$(dirname "$0")" && pwd -P)"/..}
+runfiles="${runfiles:-$(pwd)}"
+export PATH="${runfiles}/hack/bin:${runfiles}/hack/brodocs:${PATH}"
+cd "${REPO_ROOT}"

 REFERENCE_PATH="docs/generated/reference"
-REFERENCE_ROOT=$(cd "${SCRIPT_ROOT}/${REFERENCE_PATH}" 2> /dev/null && pwd -P)
+REFERENCE_ROOT=$(cd "${REPO_ROOT}/${REFERENCE_PATH}" 2> /dev/null && pwd -P)
 OUTPUT_DIR="${REFERENCE_ROOT}/output/reference/api-docs"

 ## cleanup removes files that are leftover from running various tools and not required
@ -37,72 +34,66 @@ cleanup() {
    pushd "${REFERENCE_ROOT}"
    echo "+++ Cleaning up temporary docsgen files"
    # Clean up old temporary files
-    find "${OUTPUT_DIR}" \
-        \( -type l -o -type f \) \
-        -not -name bootstrap.min.css \
-        -not -name font-awesome.min.css \
-        -not -name highlight.js \
-        -not -name stylesheet.css \
-        -not -name index.html \
-        -not -name scroll.js \
-        -not -name tabvisibility.js \
-        -not -name default.css \
-        -not -name navData.js \
-        -not -name jquery.min.js \
-        -not -name jquery.scrollTo.min.js \
-        -not -name fontawesome-webfont.ttf \
-        -not -name fontawesome-webfont.woff \
-        -not -name fontawesome-webfont.woff2 \
-        -exec rm -Rf {} \; || true
-    find "${OUTPUT_DIR}" \
-        -type d \
-        -depth \
-        -exec rmdir {} \; > /dev/null 2>&1
-    rm -Rf "openapi-spec" "openapi" "includes" "manifest.json"
-
+    rm -Rf "openapi-spec" "includes" "manifest.json"
    popd
 }

+# Ensure we start with a clean set of directories
 trap cleanup EXIT
-
-mkdir -p "${OUTPUT_DIR}"
-
 cleanup
 echo "+++ Removing old output"
 rm -Rf "${OUTPUT_DIR}"

-echo "+++ Creating temporary directories"
+echo "+++ Creating temporary output directories"

-# Create all required directories
+# Generate swagger.json from the Golang generated openapi spec
+echo "+++ Running 'swagger-gen' to generate swagger.json"
 mkdir -p "${REFERENCE_ROOT}/openapi-spec"
-mkdir -p "${REFERENCE_ROOT}/openapi"
-mkdir -p "${OUTPUT_DIR}"
-# Create a placeholder .go file to prevent issues with openapi-gen
-echo "package openapi" > "${REFERENCE_ROOT}/openapi/openapi_generated.go"
-
-echo "+++ Building openapi-gen"
-OPENAPI_GEN="$(mktemp)"
-go build -o "${OPENAPI_GEN}" ./vendor/k8s.io/code-generator/cmd/openapi-gen
-
-echo "+++ Generating openapi_generated.go into 'github.com/jetstack/cert-manager/${REFERENCE_PATH}/openapi'"
-# Generate Golang types for OpenAPI spec
-${OPENAPI_GEN} \
-        --input-dirs github.com/jetstack/cert-manager/pkg/apis/certmanager/v1alpha1,k8s.io/apimachinery/pkg/apis/meta/v1,k8s.io/apimachinery/pkg/runtime,k8s.io/apimachinery/pkg/version \
-        --output-package "github.com/jetstack/cert-manager/${REFERENCE_PATH}/openapi"
-
-echo "+++ Running './${REFERENCE_PATH}/main.go'"
 # Generate swagger.json
-go run "./${REFERENCE_PATH}/main.go"
+# TODO: can we output to a tmpfile instead of in the repo?
+swagger-gen > "${REFERENCE_ROOT}/openapi-spec/swagger.json"

 echo "+++ Running gen-apidocs"
 # Generate Markdown docs
 gen-apidocs \
    --copyright "<a href=\"https://jetstack.io\">Copyright 2018 Jetstack Ltd.</a>" \
    --title "Cert-manager API Reference" \
-    --config-dir ./docs/generated/reference/
+    --config-dir "${REFERENCE_ROOT}"

 echo "+++ Running brodocs"
-INCLUDES_DIR="${REFERENCE_ROOT}/includes" \
-OUTPUT_DIR="${OUTPUT_DIR}" \
-MANIFEST_PATH="${REFERENCE_ROOT}/manifest.json" \
-runbrodocs.sh
+mkdir -p "${OUTPUT_DIR}"
+
+# Running a bazel-built target from the 'bazel run' context has some nuances
+# which cause runfiles to not be visible properly.
+# We fudge the vars used by the runfiles loader snippet to point to the correct
+# runfiles.
+# We depend on brodocs itself, and include all its dependencies as a dependency
+# of this target.
+BRODOCS_RUNFILES="${runfiles}/.."
+RUNFILES_DIR="${BRODOCS_RUNFILES}" brodocs \
+    "${REFERENCE_ROOT}/manifest.json" \
+    "${REFERENCE_ROOT}/includes" \
+    "${OUTPUT_DIR}"
+
+BAZEL_BRODOCS_PATH="${BRODOCS_RUNFILES}/brodocs"
+BAZEL_BRODOCS_NODE_MODULES="${BRODOCS_RUNFILES}/brodocs_modules/node_modules"
+
+# Copy across support files for docs.
+# These commands had to be manually written after inspecting the required output.
+cp "${BAZEL_BRODOCS_PATH}"/stylesheet.css \
+   "${BAZEL_BRODOCS_PATH}"/scroll.js \
+   "${BAZEL_BRODOCS_PATH}"/actions.js \
+   "${BAZEL_BRODOCS_PATH}"/tabvisibility.js \
+   "${OUTPUT_DIR}/"
+mkdir -p "${OUTPUT_DIR}/node_modules/jquery/dist"
+cp "${BAZEL_BRODOCS_NODE_MODULES}/jquery/dist/jquery.min.js" "${OUTPUT_DIR}/node_modules/jquery/dist/"
+mkdir -p "${OUTPUT_DIR}/node_modules/bootstrap/dist/css"
+cp "${BAZEL_BRODOCS_NODE_MODULES}/bootstrap/dist/css/bootstrap.min.css" "${OUTPUT_DIR}/node_modules/bootstrap/dist/css/"
+mkdir -p "${OUTPUT_DIR}/node_modules/font-awesome/css"
+cp "${BAZEL_BRODOCS_NODE_MODULES}/font-awesome/css/"* "${OUTPUT_DIR}/node_modules/font-awesome/css/"
+mkdir -p "${OUTPUT_DIR}/node_modules/font-awesome/fonts"
+cp "${BAZEL_BRODOCS_NODE_MODULES}/font-awesome/fonts/"* "${OUTPUT_DIR}/node_modules/font-awesome/fonts/"
+mkdir -p "${OUTPUT_DIR}/node_modules/highlight.js/styles"
+cp "${BAZEL_BRODOCS_NODE_MODULES}/highlight.js/styles/default.css" "${OUTPUT_DIR}/node_modules/highlight.js/styles/"
+mkdir -p "${OUTPUT_DIR}/node_modules/jquery.scrollto"
+cp "${BAZEL_BRODOCS_NODE_MODULES}/jquery.scrollto/jquery.scrollTo.min.js" "${OUTPUT_DIR}/node_modules/jquery.scrollto/"
--- a/hack/verify-reference-docs.sh
+++ b/hack/verify-reference-docs.sh
@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash

 # Copyright 2018 The Jetstack cert-manager contributors.
 #
@ -18,31 +18,37 @@ set -o errexit
 set -o nounset
 set -o pipefail

+RULE_NAME="reference-docs"
+
 SCRIPT_ROOT=$(dirname "${BASH_SOURCE}")/..

-DIFFROOT="${SCRIPT_ROOT}/docs/generated/reference/output"
-TMP_DIFFROOT="${SCRIPT_ROOT}/_tmp/docs/generated/reference/output"
-_tmp="${SCRIPT_ROOT}/_tmp"
+_tmp="$(mktemp -d)"
+DIFFROOT="${SCRIPT_ROOT}/"

 cleanup() {
  rm -rf "${_tmp}"
 }
 trap "cleanup" EXIT SIGINT

-cleanup
+# Create a fake GOPATH
+export GOPATH="${_tmp}"
+TMP_DIFFROOT="${GOPATH}/src/github.com/jetstack/cert-manager"

 mkdir -p "${TMP_DIFFROOT}"
-cp -a "${DIFFROOT}"/* "${TMP_DIFFROOT}"
+rsync -avvL "${DIFFROOT}"/ "${TMP_DIFFROOT}" >/dev/null

-"${SCRIPT_ROOT}/hack/update-reference-docs-dockerized.sh"
-echo "diffing ${DIFFROOT} against freshly generated reference docs"
+export runfiles="$(pwd)"
+cd "${TMP_DIFFROOT}"
+export BUILD_WORKSPACE_DIRECTORY="$(pwd)"
+"hack/update-${RULE_NAME}.sh"
+
+echo "diffing ${DIFFROOT} against freshly generated ${RULE_NAME}"
 ret=0
-diff -Naupr "${DIFFROOT}" "${TMP_DIFFROOT}" || ret=$?
-cp -a "${TMP_DIFFROOT}"/* "${DIFFROOT}"
+diff --exclude=__main__ -Naupr "${DIFFROOT}/docs/generated/reference/output" "${TMP_DIFFROOT}/docs/generated/reference/output" || ret=$?
 if [[ $ret -eq 0 ]]
 then
  echo "${DIFFROOT} up to date."
 else
-  echo "${DIFFROOT} is out of date. Please run hack/update-reference-docs.sh"
+  echo "${DIFFROOT} is out of date. Please run 'bazel run //hack:update-${RULE_NAME}'"
  exit 1
-fi
+fi