diff --git a/docs/generated/reference/.gitignore b/docs/generated/reference/.gitignore new file mode 100644 index 000000000..d28fd59a9 --- /dev/null +++ b/docs/generated/reference/.gitignore @@ -0,0 +1,4 @@ +/manifest.json +/openapi +/openapi-spec +/includes diff --git a/docs/generated/reference/config.yaml b/docs/generated/reference/config.yaml new file mode 100644 index 000000000..d85b5ea63 --- /dev/null +++ b/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" diff --git a/docs/generated/reference/main.go b/docs/generated/reference/main.go new file mode 100644 index 000000000..a38db6f17 --- /dev/null +++ b/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) + } +} diff --git a/docs/generated/reference/static_includes/_certmanager.md b/docs/generated/reference/static_includes/_certmanager.md new file mode 100644 index 000000000..c15dca97c --- /dev/null +++ b/docs/generated/reference/static_includes/_certmanager.md @@ -0,0 +1,9 @@ + +# cert-manager + +------------ + +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/). diff --git a/docs/generated/reference/static_includes/_definitions.md b/docs/generated/reference/static_includes/_definitions.md new file mode 100644 index 000000000..091e5a53d --- /dev/null +++ b/docs/generated/reference/static_includes/_definitions.md @@ -0,0 +1,5 @@ + +# Field Definitions + +------------ + diff --git a/docs/generated/reference/static_includes/_oldversions.md b/docs/generated/reference/static_includes/_oldversions.md new file mode 100644 index 000000000..5b434aeaf --- /dev/null +++ b/docs/generated/reference/static_includes/_oldversions.md @@ -0,0 +1,5 @@ + +# Old API Versions + +------------ + diff --git a/docs/generated/reference/static_includes/_overview.md b/docs/generated/reference/static_includes/_overview.md new file mode 100644 index 000000000..e2584e964 --- /dev/null +++ b/docs/generated/reference/static_includes/_overview.md @@ -0,0 +1,6 @@ + +# Overview + +------------ + +Some kind of overview here \ No newline at end of file diff --git a/hack/update-reference-docs-dockerized.sh b/hack/update-reference-docs-dockerized.sh new file mode 100755 index 000000000..83dbfc3ac --- /dev/null +++ b/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 diff --git a/hack/update-reference-docs.sh b/hack/update-reference-docs.sh new file mode 100755 index 000000000..474cdea98 --- /dev/null +++ b/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 "Copyright 2018 Jetstack Ltd." \ + --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 diff --git a/pkg/apis/certmanager/v1alpha1/types.go b/pkg/apis/certmanager/v1alpha1/types.go index bfea2a0ba..dcc0b186d 100644 --- a/pkg/apis/certmanager/v1alpha1/types.go +++ b/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"`