Skip to content

Commit

Permalink
Website documentation (grafana#274)
Browse files Browse the repository at this point in the history
* website documentation

Signed-off-by: Ruben Vargas <[email protected]>

* add tempo-operator slack to contributing

Signed-off-by: Ruben Vargas <[email protected]>

* change website base url default

Signed-off-by: Ruben Vargas <[email protected]>

* fix LICENCE and README.md links

Signed-off-by: Ruben Vargas <[email protected]>

---------

Signed-off-by: Ruben Vargas <[email protected]>
  • Loading branch information
rubenvp8510 authored Mar 7, 2023
1 parent 152e8c5 commit 3b20257
Show file tree
Hide file tree
Showing 43 changed files with 6,827 additions and 2,106 deletions.
6 changes: 6 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -17,3 +17,9 @@ bin/

# Files generated by e2e tests
kubeconfig

# website

website/public/*
website/resources/*
docs/prologue/contributing.md
3 changes: 3 additions & 0 deletions .gitmodules
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
[submodule "website/themes/doks"]
path = website/themes/doks
url = https://github.com/h-enk/doks.git
32 changes: 32 additions & 0 deletions ADOPTERS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
---
title: Adopters
lead: ""
date: 2021-04-30T10:40:00+00:00
lastmod: 2021-04-30T10:40:00+00:00
draft: false
images: []
---

<!--
Insert your entry using this template keeping the list alphabetically sorted:
## <Company/Organization Name>
https://our-link.com/
Environments: AWS, Azure, Google Cloud, Bare Metal, etc
Details (optional):
- Ruler for Tempostack
-->

This document tracks people and use cases for the Tempo Operator in production. By creating a list of production use cases we hope to build a community of advisors that we can reach out to with experience using various the Tempo Operator applications, operation environments, and cluster sizes. The Tempo Operator development team may reach out periodically to check-in on how the Tempo Operator is working in the field and update this list.


## Red Hat Inc

https://www.redhat.com

Environments: AWS, Azure, Google Cloud, Bare Metal, etc
46 changes: 46 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
---
title: Contributing
description: How can I contribute to the Tempo Operator?
lead: ""
lastmod: "2021-03-08T08:48:57+00:00"
draft: false
images: []
menu:
docs:
parent: prologue
weight: 200
toc: true
---

This project is licensed under the [AGPLv3 license](LICENSE) and accept
contributions via GitHub pull requests. This document outlines some of the
conventions on development workflow, contact points
and other resources to make it easier to get your contribution accepted.


# Contributor License Agreement

By contributing to this project you agree to the Contributor License Agreement.

# Email and Chat

The project currently uses the [Grafana Slack](https://grafana.slack.com):
- [#tempo-operator-dev](https://grafana.slack.com/archives/C0414EUU39A)

## Getting Started

- Fork the repository on GitHub
- Read the [README](README.md) for build and test instructions
- Play with the project, submit bugs, submit patches!

## Contribution Flow

This is a rough outline of what a contributor's workflow looks like:

- Create a topic branch from where you want to base your work (usually `main`).
- Make commits of logical units.
- Push your changes to a topic branch in your fork of the repository.
- Make sure the tests pass, and add any new tests as appropriate.
- Submit a pull request to the original repository.

Thanks for your contributions!
2 changes: 1 addition & 1 deletion Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ FROM golang:1.19 as builder
WORKDIR /workspace
# Cache tool dependencies
COPY Makefile Makefile
RUN make controller-gen crdoc kustomize
RUN make controller-gen gen-crd-api-reference-docs kustomize
# Copy the Go Modules manifests
COPY go.mod go.mod
COPY go.sum go.sum
Expand Down
73 changes: 58 additions & 15 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,13 @@ IMG_REPO ?= tempo-operator
IMG ?= ${IMG_PREFIX}/${IMG_REPO}:v${OPERATOR_VERSION}
BUNDLE_IMG ?= ${IMG_PREFIX}/${IMG_REPO}-bundle:v${OPERATOR_VERSION}


# Website generation variables
WEBSITE_DIR ?= website
WEBSITE_BASE_URL ?= https://tempo-operator.netlify.app
HUGO_VERSION = v0.80.0


# When the VERBOSE variable is set to 1, all the commands are shown
ifeq ("$(VERBOSE)","true")
echo_prefix=">>>>"
Expand Down Expand Up @@ -163,19 +170,20 @@ $(LOCALBIN):
## Tool Versions
KUSTOMIZE_VERSION ?= v4.5.5
CONTROLLER_TOOLS_VERSION ?= v0.9.2
CRDOC_VERSION ?= v0.5.2
OPERATOR_SDK_VERSION ?= 1.27.0
GEN_CRD_VERSION ?= v0.0.5
ENVTEST_VERSION ?= latest
OPERATOR_SDK_VERSION ?= 1.27.0
CERTMANAGER_VERSION ?= 1.9.1

## Tool Binaries
KUSTOMIZE ?= $(LOCALBIN)/kustomize-$(KUSTOMIZE_VERSION)
CONTROLLER_GEN ?= $(LOCALBIN)/controller-gen-$(CONTROLLER_TOOLS_VERSION)
ENVTEST ?= $(LOCALBIN)/setup-envtest-$(ENVTEST_VERSION)
CRDOC = $(LOCALBIN)/crdoc-$(CRDOC_VERSION)
GEN_CRD = $(LOCALBIN)/gen-crd-api-reference-docs-$(GEN_CRD_VERSION)
OPERATOR_SDK ?= $(LOCALBIN)/operator-sdk-$(OPERATOR_SDK_VERSION)
KIND ?= $(LOCALBIN)/kind
KUTTL ?= $(LOCALBIN)/kubectl-kuttl
HUGO ?= $(LOCALBIN)/hugo-$(HUGO_VERSION)

# Options for KIND version to use
export KUBE_VERSION ?= 1.25
Expand Down Expand Up @@ -255,18 +263,10 @@ ci: test ensure-generate-is-noop
lint:
golangci-lint run

.PHONY: api-docs
api-docs: crdoc kustomize
@{ \
set -e ;\
TMP_DIR=$$(mktemp -d) ; \
$(KUSTOMIZE) build config/crd -o $$TMP_DIR/crd-output.yaml ;\
$(CRDOC) --resources $$TMP_DIR/crd-output.yaml --output docs/api.md ;\
}

.PHONY: crdoc
crdoc: ## Download crdoc locally if necessary.
test -s $(LOCALBIN)/crdoc-$(CRDOC_VERSION) || $(call go-get-tool,$(CRDOC), fybrik.io/crdoc,$(CRDOC_VERSION))
.PHONY: gen-crd-api-reference-docs
gen-crd-api-reference-docs: ## Download gen-crd-api-reference-docs locally if necessary.
test -s $(GEN_CRD) || $(call go-get-tool,$(GEN_CRD),github.com/ViaQ/gen-crd-api-reference-docs,$(GEN_CRD_VERSION))


.PHONY: kustomize
Expand Down Expand Up @@ -357,7 +357,8 @@ ensure-generate-is-noop: generate bundle
@git diff -s --exit-code apis/config/v1alpha1/zz_generated.*.go || (echo "Build failed: a model has been changed but the generated resources aren't up to date. Run 'make generate' and update your PR." && exit 1)
@git diff -s --exit-code bundle config || (echo "Build failed: the bundle, config files has been changed but the generated bundle, config files aren't up to date. Run 'make bundle' and update your PR." && git diff && exit 1)
@git diff -s --exit-code bundle.Dockerfile || (echo "Build failed: the bundle.Dockerfile file has been changed. The file should be the same as generated one. Run 'make bundle' and update your PR." && git diff && exit 1)
@git diff -s --exit-code docs/api.md || (echo "Build failed: the api.md file has been changed but the generated api.md file isn't up to date. Run 'make api-docs' and update your PR." && git diff && exit 1)
@git diff -s --exit-code docs/operator/api.md || (echo "Build failed: the api.md file has been changed but the generated api.md file isn't up to date. Run 'make api-docs' and update your PR." && git diff && exit 1)
@git diff -s --exit-code docs/operator/feature-gates.md || (echo "Build failed: the feature-gates.md file has been changed but the generated feature-gates.md file isn't up to date. Run 'make api-docs' and update your PR." && git diff && exit 1)

.PHONY: cert-manager
cert-manager: cmctl
Expand All @@ -381,3 +382,45 @@ cmctl:
mv $$TMP_DIR/cmctl $(CMCTL) ;\
rm -rf $$TMP_DIR ;\
}

.PHONY: api-docs
api-docs: docs/operator/api.md docs/operator/feature-gates.md

##@ Website
TYPES_TARGET := $(shell find apis/tempo -type f -iname "*_types.go")
docs/operator/api.md: $(TYPES_TARGET) gen-crd-api-reference-docs
$(GEN_CRD) -api-dir "github.com/os-observability/tempo-operator/apis/tempo/" -config "$(PWD)/config/docs/config.json" -template-dir "$(PWD)/config/docs/templates" -out-file "$(PWD)/$@"
sed -i 's/+docs:/ docs:/' $@
sed -i 's/+parent:/ parent:/' $@
sed -i 's/##/\n##/' $@
sed -i 's/+newline/\n/' $@


FEATURE_GATES_TARGET := $(shell find apis/config -type f -iname "*_types.go")
docs/operator/feature-gates.md: $(FEATURE_GATES_TARGET) gen-crd-api-reference-docs
$(GEN_CRD) -api-dir "github.com/os-observability/tempo-operator/apis/config/v1alpha1/" -config "$(PWD)/config/docs/config.json" -template-dir "$(PWD)/config/docs/templates" -out-file "$(PWD)/$@"
sed -i 's/title: "API"/title: "Feature Gates"/' $@
sed -i 's/+docs:/ docs:/' $@
sed -i 's/+parent:/ parent:/' $@
sed -i 's/##/\n##/' $@
sed -i 's/+newline/\n/' $@

.PHONY: web-pre
web-pre: docs/operator/api.md docs/operator/feature-gates.md
@echo ">> preprocessing docs for website"
@git submodule update --init --recursive
cp CONTRIBUTING.md docs/prologue/contributing.md
sed -i 's/(LICENSE)/(https:\/\/raw.githubusercontent.com\/os-observability\/tempo-operator\/main\/LICENSE)/' docs/prologue/contributing.md
sed -i 's/(README.md)/(https:\/\/github.com\/os-observability\/tempo-operator#readme)/' docs/prologue/contributing.md
cd $(WEBSITE_DIR)/themes/doks/ && npm install && rm -rf content

.PHONY: web
web: web-pre hugo ## Run production build of the tempo-operator.dev website
cd $(WEBSITE_DIR) && $(HUGO) -b $(WEBSITE_BASE_URL)

.PHONY: web-serve
web-serve: web-pre ## Run local preview version of the tempo-operator.dev website
@cd $(WEBSITE_DIR) && $(HUGO) serve

hugo:
test -s $(HUGO) || $(call go-get-tool,$(HUGO),--tags extended github.com/gohugoio/hugo,$(HUGO_VERSION))
4 changes: 4 additions & 0 deletions apis/config/v1alpha1/doc.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
// Package v1alpha1 contains API Schema definitions for the config.tempo v1alpha1 API group.
// +kubebuilder:object:generate=true
// +groupName=config.tempo.grafana.com
package v1alpha1
1 change: 1 addition & 0 deletions apis/tempo/register.go
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
package tempo
4 changes: 4 additions & 0 deletions apis/tempo/v1alpha1/doc.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
// Package v1alpha1 contains API Schema definitions for the tempo v1alpha1 API group.
// +kubebuilder:object:generate=true
// +groupName=tempo.grafana.com
package v1alpha1
64 changes: 64 additions & 0 deletions config/docs/config.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
{
"hideMemberFields": [
"TypeMeta"
],
"hideTypePatterns": [
"ParseError$",
"List$"
],
"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/util/intstr\\.IntOrString$",
"docsURLTemplate": "https://pkg.go.dev/k8s.io/apimachinery/pkg/util/intstr#IntOrString"
},
{
"typeMatchPrefix": "^k8s\\.io/(api|apimachinery/pkg/apis)/",
"docsURLTemplate": "https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#{{lower .TypeIdentifier}}-{{arrIndex .PackageSegments -1}}-{{arrIndex .PackageSegments -2}}"
},
{
"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/os-observability/tempo-operator/apis/tempo/v1alpha1",
"docsURLTemplate": "../v1/api.md#tempo.grafana.com/v1alpha1.{{ .TypeIdentifier}}"
},
{
"typeMatchPrefix": "^github\\.com/os-observability/tempo-operator/apis/config/v1alpha1",
"docsURLTemplate": "../v1/feature-gates.md#tempo-grafana-com-v1alpha1-{{ .TypeIdentifier}}"
},
{
"typeMatchPrefix": "^k8s\\.io/component-base/config/v1alpha1\\.LeaderElectionConfiguration$",
"docsURLTemplate": "https://pkg.go.dev/k8s.io/component-base/config#LeaderElectionConfiguration"
},
{
"typeMatchPrefix": "^sigs\\.k8s\\.io/controller-runtime/pkg/config/v1alpha1\\.ControllerConfigurationSpec$",
"docsURLTemplate": "https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/config/v1alpha1#ControllerConfigurationSpec"
},
{
"typeMatchPrefix": "^sigs\\.k8s\\.io/controller-runtime/pkg/config/v1alpha1\\.ControllerMetrics$",
"docsURLTemplate": "https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/config/v1alpha1#ControllerMetrics"
},
{
"typeMatchPrefix": "^sigs\\.k8s\\.io/controller-runtime/pkg/config/v1alpha1\\.ControllerHealth$",
"docsURLTemplate": "https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/config/v1alpha1#ControllerHealth"
},
{
"typeMatchPrefix": "^sigs\\.k8s\\.io/controller-runtime/pkg/config/v1alpha1\\.ControllerWebhook$",
"docsURLTemplate": "https://pkg.go.dev/sigs.k8s.io/controller-runtime/pkg/config/v1alpha1#ControllerWebhook"
}
],
"typeDisplayNamePrefixOverrides": {
"k8s.io/api/": "Kubernetes ",
"k8s.io/apimachinery/pkg/apis/": "Kubernetes ",
"k8s.io/component-base/config/": "Kubernetes ",
"sigs.k8s.io/controller-runtime/pkg/config/": "K8S Controller-runtime ",
"github.com/os-observability/tempo-operator/apis/tempo/v1alpha1": "Tempo Operator v1alpha1",
"github.com/os-observability/tempo-operator/apis/config/v1alpha1": "Feature Gates"
},
"markdownDisabled": false
}
45 changes: 45 additions & 0 deletions config/docs/templates/members.tpl
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
{{ define "member" }}
{{ if not (hiddenMember .)}}
{{ if fieldEmbedded . }}
{{ range .Type.Members }}
{{ template "member" . }}
{{ end }}
{{ else }}
<tr>
<td>
<code>{{ fieldName . }}</code><br/>
<em>
{{ if linkMDForType .Type }}
<a href="{{ linkMDForType .Type }}">
{{ typeDisplayName .Type }}
</a>
{{ else }}
{{ typeDisplayName .Type }}
{{ end }}
</em>
</td>
<td>
{{ if isOptionalMember .}}
<em>(Optional)</em>
{{ end }}

{{ safe (renderComments .CommentLines) }}

{{ if and (eq (.Type.Name.Name) "ObjectMeta") }}
Refer to the Kubernetes API documentation for the fields of the
<code>metadata</code> field.
{{ end }}

</td>
</tr>
{{ end }}
{{ end }}
{{ end }}

{{ define "members" }}

{{ range .Members }}
{{ template "member" . }}
{{ end }}

{{ end }}
39 changes: 39 additions & 0 deletions config/docs/templates/pkg.tpl
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
{{ define "packages" }}
---
title: "API"
description: "Generated API docs for the Tempo Operator"
lead: ""
draft: false
images: []
menu:
+docs:
+parent: "operator"
weight: 1000
toc: true
---

This Document contains the types introduced by the Tempo Operator to be consumed by users.

> This page is automatically generated with `gen-crd-api-reference-docs`.

{{ range .packages }}
# {{ packageDisplayName . }} { #{{packageMDAnchorID . }} }
{{ with (index .GoPackages 0 )}}
{{ with .DocComments }}
<div>
{{ safe (renderComments .) }}
</div>
{{ end }}
{{ end }}

<b>Resource Types:</b>

{{ range (visibleTypes (sortedTypes .Types))}}
{{ template "type" . }}
{{ end }}
<hr/>
+newline
{{ end }}

{{ end }}

Loading

0 comments on commit 3b20257

Please sign in to comment.