Add script for generating reference docs

docs/generated/reference/.gitignore

@@ -0,0 +1,4 @@
+/manifest.json
+/openapi
+/openapi-spec
+/includes

docs/generated/reference/config.yaml

@@ -0,0 +1,16 @@
+example_location: "examples"
+api_groups: 
+  - "Certmanager"
+resource_categories: 
+- name: "Certmanager"
+  include: "certmanager"
+  resources: 
+  - name: "Certificate"
+    version: "v1alpha1"
+    group: "certmanager"
+  - name: "ClusterIssuer"
+    version: "v1alpha1"
+    group: "certmanager"
+  - name: "Issuer"
+    version: "v1alpha1"
+    group: "certmanager"

docs/generated/reference/main.go

@@ -0,0 +1,54 @@
+/*
+Copyright YEAR Jetstack Ltd.
+
+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"
+	"io/ioutil"
+	"log"
+	"path/filepath"
+	"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)
+	}
+	err = ioutil.WriteFile(filepath.Join("docs", "generated", "reference", "openapi-spec", "swagger.json"), o, 0700)
+	if err != nil {
+		log.Fatalf("%v", err)
+	}
+}

docs/generated/reference/static_includes/_certmanager.md

@@ -0,0 +1,9 @@
+
+# <strong>cert-manager</strong>
+
+------------
+
+This page contains reference documentation for cert-manager API types.
+
+For full documentation on how to use cert-manager, please view our
+[official documentation](https://cert-manager.readthedocs.io/).

docs/generated/reference/static_includes/_definitions.md

@@ -0,0 +1,5 @@
+
+# <strong>Field Definitions</strong>
+
+------------
+

docs/generated/reference/static_includes/_oldversions.md

@@ -0,0 +1,5 @@
+
+# <strong>Old API Versions</strong>
+
+------------
+

docs/generated/reference/static_includes/_overview.md

@@ -0,0 +1,6 @@
+
+# <strong>Overview</strong>
+
+------------
+
+Some kind of overview here

hack/update-reference-docs-dockerized.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+
+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

hack/update-reference-docs.sh

@@ -0,0 +1,94 @@
+#!/bin/bash
+
+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}")/..
+
+REFERENCE_PATH="docs/generated/reference"
+REFERENCE_ROOT=$(cd "${SCRIPT_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
+## for the actual output
+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"
+
+    popd
+}
+
+trap cleanup EXIT
+
+mkdir -p "${OUTPUT_DIR}"
+
+cleanup
+echo "+++ Removing old output"
+rm -Rf "${OUTPUT_DIR}"
+
+echo "+++ Creating temporary directories"
+
+# Create all required directories
+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"
+
+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/
+
+echo "+++ Running brodocs"
+INCLUDES_DIR="${REFERENCE_ROOT}/includes" \
+OUTPUT_DIR="${OUTPUT_DIR}" \
+MANIFEST_PATH="${REFERENCE_ROOT}/manifest.json" \
+runbrodocs.sh

pkg/apis/certmanager/v1alpha1/types.go

@@ -31,8 +31,8 @@ const (
 // +genclient:nonNamespaced
 // +k8s:openapi-gen=true
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
-// +resource:path=clusterissuers
 
+// +kubebuilder:resource:path=clusterissuers
 type ClusterIssuer struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
@@ -54,8 +54,8 @@ type ClusterIssuerList struct {
 // +genclient
 // +k8s:openapi-gen=true
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
-// +resource:path=issuers
 
+// +kubebuilder:resource:path=issuers
 type Issuer struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
@@ -266,8 +266,8 @@ type ACMEIssuerStatus struct {
 // +genclient
 // +k8s:openapi-gen=true
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
-// +resource:path=certificates
 
+// +kubebuilder:resource:path=certificates
 // Certificate is a type to represent a Certificate from ACME
 type Certificate struct {
 	metav1.TypeMeta   `json:",inline"`