From ade00f6e17c9ca1913378f8fc6ed522f5810ae8d Mon Sep 17 00:00:00 2001 From: Gergely Brautigam <182850+Skarlso@users.noreply.github.com> Date: Mon, 20 Nov 2023 16:43:50 +0100 Subject: [PATCH 1/2] docs: update the README and add relevant information --- README.md | 145 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 88 insertions(+), 57 deletions(-) diff --git a/README.md b/README.md index e147994..94eec56 100644 --- a/README.md +++ b/README.md @@ -3,79 +3,110 @@ [![REUSE status](https://api.reuse.software/badge/github.com/open-component-model/git-controller)](https://api.reuse.software/info/github.com/open-component-model/git-controller) ## Description -// TODO(user): An in-depth paragraph about your project and overview of use -## Getting Started -You’ll need a Kubernetes cluster to run against. You can use [KIND](https://sigs.k8s.io/kind) to get a local cluster for testing, or run against a remote cluster. -**Note:** Your controller will automatically use the current context in your kubeconfig file (i.e. whatever cluster `kubectl cluster-info` shows). - -### Running on the cluster -1. Install Instances of Custom Resources: - -```sh -kubectl apply -f config/samples/ +This is the main repository for `git-controller`. The `git-controller` is designed to enable the automated deployment of +software using the [Open Component Model](https://ocm.software) and Flux. + +## Functionality + +`git-controller` provides the following two main functionalities. + +### Syncing + +The `Sync` API objects takes a snapshot's output and pushes it into a specific repository using some pre-configured +commit information. + +A sample yaml for running a sync operation can look something like this: + +```yaml +apiVersion: delivery.ocm.software/v1alpha1 +kind: Sync +metadata: + name: git-sample + namespace: ocm-system +spec: + commitTemplate: + email: e2e-tester@gitea.com + message: "Update made from git-controller" + name: Testy McTestface + interval: 10m0s + subPath: . + snapshotRef: + name: podinfo-deployment-t5bhemw + repositoryRef: + name: new-repository-2 # The name of the Repository object that contains access information to the repository. + automaticPullRequestCreation: true ``` -2. Build and push your image to the location specified by `IMG`: - -```sh -make docker-build docker-push IMG=/git-controller:tag -``` +The `repositoryRef` information contains a link to the Repository object explained in section [Repository Management](#repository-management). +That object contains information on how to access the repository and what credentials to use. -3. Deploy the controller to the cluster with the image specified by `IMG`: +Setting `automaticPullRequestCreation: true` will create a Pull Request of the changes. If no branch information is +provided the changes are created from a random generated branch to `main`. The pull request can further be fine-tuned +with the following details: -```sh -make deploy IMG=/git-controller:tag +```yaml +pullRequestTemplate: + title: This is the title that will be used. + description: Contains more information about the Pull Request. + base: feature-branch-1 ``` -### Uninstall CRDs -To delete the CRDs from the cluster: - -```sh -make uninstall +### Repository Management + +The Repository object manages git repositories for supported providers. At the moment of this writing the following +providers are supported: +- GitHub +- Gitlab +- Gitea + +The main objective of this object is to create a Repository. Along that, it also sets up some branch protection rules. +Branch protection rules are used during the Validation processes in the MPAS environment. + +A sample repository could look something like this: + +```yaml +apiVersion: mpas.ocm.software/v1alpha1 +kind: Repository +metadata: + name: new-repository-2 + namespace: mpas-system +spec: + isOrganization: false + visibility: public + credentials: + secretRef: + name: git-sync-secret + interval: 10m + owner: Skarlso + provider: github + existingRepositoryPolicy: adopt ``` -### Undeploy controller -UnDeploy the controller to the cluster: - -```sh -make undeploy -``` +There are several things here to unpack. First, is the organization. This needs to be set in case the owner of the +future repository is an organization. By default, this is set to `true`. Here, we use `false` for testing purposes. -## Contributing -// TODO(user): Add detailed information on how you would like others to contribute to this project +The second is `visibility`. This can be switched from `public` to `private`. -### How it works -This project aims to follow the Kubernetes [Operator pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/) +`credentials` are self-explanatory. Either a token or SSH credentials are supported. -It uses [Controllers](https://kubernetes.io/docs/concepts/architecture/controller/) -which provides a reconcile function responsible for synchronizing resources untile the desired state is reached on the cluster +Provider is between `github`, `gitlab` or `gitea`. And finally, we use `existingRepositoryPolicy` to decide what to do +in case the repository already exists. `adopt` will use the repository as is. Not setting it will fail the process if +the repository already exists. -### Test It Out -1. Install the CRDs into the cluster: +## Testing -```sh -make install -``` - -2. Run your controller (this will run in the foreground, so switch to a new terminal if you want to leave it running): - -```sh -make run -``` - -**NOTE:** You can also run this in one step by running: `make install run` - -### Modifying the API definitions -If you are editing the API definitions, generate the manifests such as CRs or CRDs using: - -```sh -make manifests -``` +`git-controller` usually doesn't run on its own. Since most of its features require a Snapshot to be present. And a +Snapshot is created by the ocm-controller. However, if testing only involves the `Repositroy` object, make sure that a +certificate TLS secret existing in the cluster with the name `ocm-registry-tls-certs`. This can be generated with +`mkcert` or by the test cluster prime script under [ocm-controller](https://github.com/open-component-model/ocm-controller/blob/4109172a978c6e07733870eda85dc2b0029e8e8b/hack/prime_test_cluster.sh). -**NOTE:** Run `make --help` for more information on all potential `make` targets +`git-controller` has a `Tiltfile` which can be used for rapid development. [tilt](https://tilt.dev/) is a convenient +little tool to spin up a controller and do some extra setup in the process conditionally. It will also keep updating +the environment via a process that is called [control loop](https://docs.tilt.dev/controlloop.html); it's similar to +a controller's reconcile loop. -More information can be found via the [Kubebuilder Documentation](https://book.kubebuilder.io/introduction.html) +To get started simple run `tilt up` then hit `` to enter Tilt's ui. You should see git-controller starting up. ## Licensing From f6bb07755dd304dcc66e8c276df350821c917bf5 Mon Sep 17 00:00:00 2001 From: Gergely Brautigam <182850+Skarlso@users.noreply.github.com> Date: Wed, 22 Nov 2023 17:06:02 +0100 Subject: [PATCH 2/2] adding API documentation --- Makefile | 15 + apis/delivery/v1alpha1/doc.go | 8 + apis/mpas/v1alpha1/doc.go | 8 + docs/apis/delivery/v1alpha1/gitcontroller.md | 469 +++++++++++++++++ docs/apis/mpas/v1alpha1/gitcontroller.md | 509 +++++++++++++++++++ hack/api-docs/config.json | 63 +++ hack/api-docs/template/members.tpl | 46 ++ hack/api-docs/template/pkg.tpl | 51 ++ hack/api-docs/template/type.tpl | 60 +++ 9 files changed, 1229 insertions(+) create mode 100644 apis/delivery/v1alpha1/doc.go create mode 100644 apis/mpas/v1alpha1/doc.go create mode 100644 docs/apis/delivery/v1alpha1/gitcontroller.md create mode 100644 docs/apis/mpas/v1alpha1/gitcontroller.md create mode 100644 hack/api-docs/config.json create mode 100644 hack/api-docs/template/members.tpl create mode 100644 hack/api-docs/template/pkg.tpl create mode 100644 hack/api-docs/template/type.tpl diff --git a/Makefile b/Makefile index 7d41be6..4fd1d50 100644 --- a/Makefile +++ b/Makefile @@ -122,6 +122,13 @@ deploy: manifests kustomize ## Deploy controller to the K8s cluster specified in undeploy: ## Undeploy controller from the K8s cluster specified in ~/.kube/config. Call with ignore-not-found=true to ignore resource not found errors during deletion. $(KUSTOMIZE) build config/default | kubectl delete --ignore-not-found=$(ignore-not-found) -f - +api-docs-mpas: gen-crd-api-reference-docs ## Generate API reference documentation + $(GEN_CRD_API_REFERENCE_DOCS) -api-dir=./apis/mpas/v1alpha1 -config=./hack/api-docs/config.json -template-dir=./hack/api-docs/template -out-file=./docs/apis/mpas/v1alpha1/gitcontroller.md + +api-docs-delivery: gen-crd-api-reference-docs ## Generate API reference documentation + $(GEN_CRD_API_REFERENCE_DOCS) -api-dir=./apis/delivery/v1alpha1 -config=./hack/api-docs/config.json -template-dir=./hack/api-docs/template -out-file=./docs/apis/delivery/v1alpha1/gitcontroller.md + + ##@ Build Dependencies ## Location to install dependencies to @@ -133,10 +140,12 @@ $(LOCALBIN): KUSTOMIZE ?= $(LOCALBIN)/kustomize CONTROLLER_GEN ?= $(LOCALBIN)/controller-gen ENVTEST ?= $(LOCALBIN)/setup-envtest +GEN_CRD_API_REFERENCE_DOCS ?= $(LOCALBIN)/gen-crd-api-reference-docs ## Tool Versions KUSTOMIZE_VERSION ?= v3.8.7 CONTROLLER_TOOLS_VERSION ?= v0.9.2 +GEN_API_REF_DOCS_VERSION ?= e327d0730470cbd61b06300f81c5fcf91c23c113 KUSTOMIZE_INSTALL_SCRIPT ?= "https://raw.githubusercontent.com/kubernetes-sigs/kustomize/master/hack/install_kustomize.sh" .PHONY: kustomize @@ -163,3 +172,9 @@ generate-license: $$f \ --skip-unrecognised; \ done + +# Find or download gen-crd-api-reference-docs +.PHONY: gen-crd-api-reference-docs +gen-crd-api-reference-docs: $(GEN_CRD_API_REFERENCE_DOCS) +$(GEN_CRD_API_REFERENCE_DOCS): $(LOCALBIN) + GOBIN=$(LOCALBIN) go install github.com/ahmetb/gen-crd-api-reference-docs@$(GEN_API_REF_DOCS_VERSION) diff --git a/apis/delivery/v1alpha1/doc.go b/apis/delivery/v1alpha1/doc.go new file mode 100644 index 0000000..d080a5c --- /dev/null +++ b/apis/delivery/v1alpha1/doc.go @@ -0,0 +1,8 @@ +// SPDX-FileCopyrightText: 2022 SAP SE or an SAP affiliate company and Open Component Model contributors. +// +// SPDX-License-Identifier: Apache-2.0 + +// Package v1alpha1 contains API Schema definitions for the delivery v1alpha1 API group +// +kubebuilder:object:generate=true +// +groupName=delivery.ocm.software +package v1alpha1 diff --git a/apis/mpas/v1alpha1/doc.go b/apis/mpas/v1alpha1/doc.go new file mode 100644 index 0000000..cf49492 --- /dev/null +++ b/apis/mpas/v1alpha1/doc.go @@ -0,0 +1,8 @@ +// SPDX-FileCopyrightText: 2022 SAP SE or an SAP affiliate company and Open Component Model contributors. +// +// SPDX-License-Identifier: Apache-2.0 + +// Package v1alpha1 contains API Schema definitions for the mpas v1alpha1 API group +// +kubebuilder:object:generate=true +// +groupName=mpas.ocm.software +package v1alpha1 diff --git a/docs/apis/delivery/v1alpha1/gitcontroller.md b/docs/apis/delivery/v1alpha1/gitcontroller.md new file mode 100644 index 0000000..7676e49 --- /dev/null +++ b/docs/apis/delivery/v1alpha1/gitcontroller.md @@ -0,0 +1,469 @@ +

OCM Controller API reference v1alpha1

+

Packages:

+ +

delivery.ocm.software/v1alpha1

+

Package v1alpha1 contains API Schema definitions for the delivery v1alpha1 API group

+Resource Types: +
    +

    CommitTemplate +

    +

    +(Appears on: +SyncSpec) +

    +

    CommitTemplate defines the details of the commit to the external repository.

    +
    +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldDescription
    +name
    + +string + +    		 +
    +email
    + +string + +    		 +
    +message
    + +string + +    		 +
    +targetBranch
    + +string + +    		 +(Optional) +
    +baseBranch
    + +string + +    		 +(Optional) +
    +
    +
    +

    PullRequestTemplate +

    +

    +(Appears on: +SyncSpec) +

    +

    PullRequestTemplate provides information for the created pull request.

    +
    +
    + + + + + + + + + + + + + + + + + + + + + +
    FieldDescription
    +title
    + +string + +    		 +
    +description
    + +string + +    		 +
    +base
    + +string + +    		 +
    +
    +
    +

    Sync +

    +

    Sync is the Schema for the syncs API

    +
    +
    + + + + + + + + + + + + + + + + + + + + + +
    FieldDescription
    +metadata
    + + +Kubernetes meta/v1.ObjectMeta + + +    		 +Refer to the Kubernetes API documentation for the fields of the +metadata field. +
    +spec
    + + +SyncSpec + + +    		 +
    +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    +snapshotRef
    + + +Kubernetes core/v1.LocalObjectReference + + +    		 +
    +repositoryRef
    + + +github.com/fluxcd/pkg/apis/meta.NamespacedObjectReference + + +    		 +
    +interval
    + + +Kubernetes meta/v1.Duration + + +    		 +
    +commitTemplate
    + + +CommitTemplate + + +    		 +
    +subPath
    + +string + +    		 +
    +prune
    + +bool + +    		 +
    +automaticPullRequestCreation
    + +bool + +    		 +(Optional) +
    +pullRequestTemplate
    + + +PullRequestTemplate + + +    		 +(Optional) +
    +
    +status
    + + +SyncStatus + + +    		 +
    +
    +
    +

    SyncSpec +

    +

    +(Appears on: +Sync) +

    +

    SyncSpec defines the desired state of Sync

    +
    +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldDescription
    +snapshotRef
    + + +Kubernetes core/v1.LocalObjectReference + + +    		 +
    +repositoryRef
    + + +github.com/fluxcd/pkg/apis/meta.NamespacedObjectReference + + +    		 +
    +interval
    + + +Kubernetes meta/v1.Duration + + +    		 +
    +commitTemplate
    + + +CommitTemplate + + +    		 +
    +subPath
    + +string + +    		 +
    +prune
    + +bool + +    		 +
    +automaticPullRequestCreation
    + +bool + +    		 +(Optional) +
    +pullRequestTemplate
    + + +PullRequestTemplate + + +    		 +(Optional) +
    +
    +
    +

    SyncStatus +

    +

    +(Appears on: +Sync) +

    +

    SyncStatus defines the observed state of Sync

    +
    +
    + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldDescription
    +digest
    + +string + +    		 +
    +observedGeneration
    + +int64 + +    		 +(Optional) +

    ObservedGeneration is the last reconciled generation.

    +
    +conditions
    + + +[]Kubernetes meta/v1.Condition + + +    		 +(Optional) +
    +pullRequestID
    + +int + +    		 +(Optional) +
    +
    +
    +
    +

    This page was automatically generated with gen-crd-api-reference-docs

    +
    diff --git a/docs/apis/mpas/v1alpha1/gitcontroller.md b/docs/apis/mpas/v1alpha1/gitcontroller.md new file mode 100644 index 0000000..8f80223 --- /dev/null +++ b/docs/apis/mpas/v1alpha1/gitcontroller.md @@ -0,0 +1,509 @@ +

    OCM Controller API reference v1alpha1

    +

    Packages:

    + +

    mpas.ocm.software/v1alpha1

    +

    Package v1alpha1 contains API Schema definitions for the mpas v1alpha1 API group

    +Resource Types: +
      +

      CommitTemplate +

      +

      +(Appears on: +RepositorySpec) +

      +

      CommitTemplate defines the commit template to use when automated commits are made.

      +
      +
      + + + + + + + + + + + + + + + + + + + + + +
      FieldDescription
      +email
      + +string + +      		 +
      +message
      + +string + +      		 +
      +name
      + +string + +      		 +
      +
      +
      +

      Credentials +

      +

      +(Appears on: +RepositorySpec) +

      +

      Credentials contains ways of authenticating the creation of a repository.

      +
      +
      + + + + + + + + + + + + + +
      FieldDescription
      +secretRef
      + + +Kubernetes core/v1.LocalObjectReference + + +      		 +
      +
      +
      +

      ExistingRepositoryPolicy +(string alias)

      +

      +(Appears on: +RepositorySpec) +

      +

      ExistingRepositoryPolicy defines what to do in case a requested repository already exists.

      +

      Repository +

      +

      Repository is the Schema for the repositories API

      +
      +
      + + + + + + + + + + + + + + + + + + + + + +
      FieldDescription
      +metadata
      + + +Kubernetes meta/v1.ObjectMeta + + +      		 +Refer to the Kubernetes API documentation for the fields of the +metadata field. +
      +spec
      + + +RepositorySpec + + +      		 +
      +
      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      +provider
      + +string + +      		 +
      +owner
      + +string + +      		 +
      +credentials
      + + +Credentials + + +      		 +
      +defaultBranch
      + +string + +      		 +(Optional) +
      +interval
      + + +Kubernetes meta/v1.Duration + + +      		 +(Optional) +
      +visibility
      + +string + +      		 +(Optional) +
      +isOrganization
      + +bool + +      		 +
      +domain
      + +string + +      		 +(Optional) +

      Domain specifies an optional domain address to be used instead of the defaults like github.com. +Must NOT contain the scheme.

      +
      +insecure
      + +bool + +      		 +(Optional) +

      Insecure should be defined if domain is not HTTPS.

      +
      +maintainers
      + +[]string + +      		 +(Optional) +
      +existingRepositoryPolicy
      + + +ExistingRepositoryPolicy + + +      		 +(Optional) +
      +commitTemplate
      + + +CommitTemplate + + +      		 +(Optional) +
      +
      +status
      + + +RepositoryStatus + + +      		 +
      +
      +
      +

      RepositorySpec +

      +

      +(Appears on: +Repository) +

      +

      RepositorySpec defines the desired state of Repository

      +
      +
      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      FieldDescription
      +provider
      + +string + +      		 +
      +owner
      + +string + +      		 +
      +credentials
      + + +Credentials + + +      		 +
      +defaultBranch
      + +string + +      		 +(Optional) +
      +interval
      + + +Kubernetes meta/v1.Duration + + +      		 +(Optional) +
      +visibility
      + +string + +      		 +(Optional) +
      +isOrganization
      + +bool + +      		 +
      +domain
      + +string + +      		 +(Optional) +

      Domain specifies an optional domain address to be used instead of the defaults like github.com. +Must NOT contain the scheme.

      +
      +insecure
      + +bool + +      		 +(Optional) +

      Insecure should be defined if domain is not HTTPS.

      +
      +maintainers
      + +[]string + +      		 +(Optional) +
      +existingRepositoryPolicy
      + + +ExistingRepositoryPolicy + + +      		 +(Optional) +
      +commitTemplate
      + + +CommitTemplate + + +      		 +(Optional) +
      +
      +
      +

      RepositoryStatus +

      +

      +(Appears on: +Repository) +

      +

      RepositoryStatus defines the observed state of Repository

      +
      +
      + + + + + + + + + + + + + + + + + +
      FieldDescription
      +observedGeneration
      + +int64 + +      		 +(Optional) +

      ObservedGeneration is the last reconciled generation.

      +
      +conditions
      + + +[]Kubernetes meta/v1.Condition + + +      		 +(Optional) +
      +
      +
      +
      +

      This page was automatically generated with gen-crd-api-reference-docs

      +
      diff --git a/hack/api-docs/config.json b/hack/api-docs/config.json new file mode 100644 index 0000000..36be1bf --- /dev/null +++ b/hack/api-docs/config.json @@ -0,0 +1,63 @@ +{ + "hideMemberFields": [ + "TypeMeta" + ], + "hideTypePatterns": [ + "ParseError$", + "List$", + "ComponentDescriptor*", + "Snapshot*" + ], + "externalPackages": [ + { + "typeMatchPrefix": "^k8s\\.io/apimachinery/pkg/apis/meta/v1\\.Duration$", + "docsURLTemplate": "https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Duration" + }, + { + "typeMatchPrefix": "^k8s\\.io/apimachinery/pkg/apis/meta/v1\\.Condition$", + "docsURLTemplate": "https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Condition" + }, + { + "typeMatchPrefix": "^k8s\\.io/(api|apimachinery/pkg/apis)/", + "docsURLTemplate": "https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#{{lower .TypeIdentifier}}-{{arrIndex .PackageSegments -1}}-{{arrIndex .PackageSegments -2}}" + }, + { + "typeMatchPrefix": "^github.com/fluxcd/pkg/apis/meta", + "docsURLTemplate": "https://pkg.go.dev/github.com/fluxcd/pkg/apis/meta#{{ .TypeIdentifier }}" + }, + { + "typeMatchPrefix": "^k8s\\.io/apiextensions-apiserver/pkg/apis/apiextensions/v1\\.JSON$", + "docsURLTemplate": "https://pkg.go.dev/k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1#JSON" + }, + { + "typeMatchPrefix": "^github\\.com/fluxcd/kustomize-controller/api/v1beta2\\.KustomizationSpec$", + "docsURLTemplate": "https://pkg.go.dev/github.com/fluxcd/kustomize-controller/api/v1beta2#KustomizationSpec" + }, + { + "typeMatchPrefix": "^github\\.com/fluxcd/helm-controller/api/v2beta1\\.HelmReleaseSpec$", + "docsURLTemplate": "https://pkg.go.dev/github.com/fluxcd/helm-controller/api/v2betapkg1#HelmReleaseSpec" + }, + { + "typeMatchPrefix": "github\\.com/open-component-model/ocm/pkg/contexts/ocm/compdesc/versions/ocm\\.software/v3alpha1\\.ComponentVersionSpec", + "docsURLTemplate": "https://pkg.go.dev/github.com/open-component-model/ocm/pkg/contexts/ocm/compdesc/versions/ocm\\.software/v3alpha1\\.ComponentVersionSpec" + }, + { + "typeMatchPrefix": "github\\.com/open-component-model/ocm/pkg/contexts/ocm/compdesc/versions/ocm\\.software/v3alpha1\\.ElementMeta", + "docsURLTemplate": "https://pkg.go.dev/github.com/open-component-model/ocm/pkg/contexts/ocm/compdesc/versions/ocm\\.software/v3alpha1\\.ElementMeta" + }, + { + "typeMatchPrefix": "github\\.com/open-component-model/ocm/pkg/contexts/ocm/compdesc/meta/v1\\.Identity", + "docsURLTemplate": "https://pkg.go.dev/github.com/open-component-model/ocm/pkg/contexts/ocm/compdesc/meta/v1/Identity" + }, + { + "typeMatchPrefix": "github\\.com/open-component-model/ocm/pkg/contexts/ocm/compdesc/meta/v1\\.Labels", + "docsURLTemplate": "https://pkg.go.dev/github.com/open-component-model/ocm/pkg/contexts/ocm/compdesc/meta/v1/Labels" + } + ], + "typeDisplayNamePrefixOverrides": { + "k8s.io/api/": "Kubernetes ", + "k8s.io/apimachinery/pkg/apis/": "Kubernetes ", + "github.com/fluxcd/pkg/apis/meta/": "Meta " + }, + "markdownDisabled": false +} diff --git a/hack/api-docs/template/members.tpl b/hack/api-docs/template/members.tpl new file mode 100644 index 0000000..26e7251 --- /dev/null +++ b/hack/api-docs/template/members.tpl @@ -0,0 +1,46 @@ +{{ define "members" }} + {{ range .Members }} + {{ if not (hiddenMember .)}} + + + {{ fieldName . }}
      + + {{ if linkForType .Type }} + + {{ typeDisplayName .Type }} + + {{ else }} + {{ typeDisplayName .Type }} + {{ end }} + + + + {{ if fieldEmbedded . }} +

      + (Members of {{ fieldName . }} are embedded into this type.) +

      + {{ end}} + + {{ if isOptionalMember .}} + (Optional) + {{ end }} + + {{ safe (renderComments .CommentLines) }} + + {{ if and (eq (.Type.Name.Name) "ObjectMeta") }} + Refer to the Kubernetes API documentation for the fields of the + metadata field. + {{ end }} + + {{ if or (eq (fieldName .) "spec") }} +
      +
      + + {{ template "members" .Type }} +
      + {{ end }} + + + {{ end }} + {{ end }} +{{ end }} diff --git a/hack/api-docs/template/pkg.tpl b/hack/api-docs/template/pkg.tpl new file mode 100644 index 0000000..cc4b538 --- /dev/null +++ b/hack/api-docs/template/pkg.tpl @@ -0,0 +1,51 @@ +{{ define "packages" }} +

      OCM Controller API reference + {{- with (index .packages 0) -}} + {{ with (index .GoPackages 0 ) -}} + {{ printf " %s" .Name -}} + {{ end -}} + {{ end }}

      + + {{ with .packages}} +

      Packages:

      + + {{ end}} + + {{ range .packages }} +

      + {{- packageDisplayName . -}} +

      + + {{ with (index .GoPackages 0 )}} + {{ with .DocComments }} + {{ safe (renderComments .) }} + {{ end }} + {{ end }} + + Resource Types: + +
        + {{- range (visibleTypes (sortedTypes .Types)) -}} + {{ if isExportedType . -}} +
      • + {{ typeDisplayName . }} +
        • + {{- end }} + {{- end -}} +
      + + {{ range (visibleTypes (sortedTypes .Types))}} + {{ template "type" . }} + {{ end }} + {{ end }} + +
      +

      This page was automatically generated with gen-crd-api-reference-docs

      +
      +{{ end }} diff --git a/hack/api-docs/template/type.tpl b/hack/api-docs/template/type.tpl new file mode 100644 index 0000000..cd2fa69 --- /dev/null +++ b/hack/api-docs/template/type.tpl @@ -0,0 +1,60 @@ +{{ define "type" }} +

      + {{- .Name.Name }} + {{ if eq .Kind "Alias" }}({{.Underlying}} alias){{ end -}} +

      + + {{ with (typeReferences .) }} +

      + (Appears on: + {{- $prev := "" -}} + {{- range . -}} + {{- if $prev -}}, {{ end -}} + {{ $prev = . }} + {{ typeDisplayName . }} + {{- end -}} + ) +

      + {{ end }} + + {{ with .CommentLines }} + {{ safe (renderComments .) }} + {{ end }} + + {{ if .Members }} +
      +
      + + + + + + + + + {{ if isExportedType . }} + + + + + + + + + {{ end }} + {{ template "members" . }} + +
      FieldDescription
      + apiVersion
      + string      		 + {{ apiGroup . }} +
      + kind
      + string +       		+ {{ .Name.Name }} +
      +
      +
      + {{ end }} +{{ end }}