Feat: provider doc generator (#5968)

Signed-off-by: iyear <ljyngup@gmail.com>
2026-08-18 03:56:36 +00:00 · 2023-05-10 10:25:35 +08:00
parent 68743841cd
commit af0556a52b
4 changed files with 294 additions and 1 deletions
@@ -89,6 +89,7 @@ require (
 	go.uber.org/zap v1.24.0 // indirect
 	golang.org/x/crypto v0.6.0
 	golang.org/x/oauth2 v0.7.0
+	golang.org/x/sync v0.1.0
 	golang.org/x/term v0.7.0
 	golang.org/x/text v0.9.0
 	golang.org/x/tools v0.7.0
@@ -290,7 +291,6 @@ require (
 	go.uber.org/atomic v1.9.0 // indirect
 	golang.org/x/mod v0.9.0 // indirect
 	golang.org/x/net v0.9.0 // indirect
-	golang.org/x/sync v0.1.0 // indirect
 	golang.org/x/sys v0.7.0 // indirect
 	golang.org/x/time v0.3.0 // indirect
 	google.golang.org/appengine v1.6.7 // indirect
@@ -0,0 +1,118 @@
+# test
+
+## #Apply
+
+
+### *Params*
+
+ Name | Description | Type | Required | Default 
+ ---- | ----------- | ---- | -------- | ------- 
+ cluster | The cluster to use. | string | true |  
+ resource | The resource to get or apply. | map[string]_ | true |  
+ options | The options to get or apply. | [options](#options) | true |  
+
+
+#### options
+
+ Name | Description | Type | Required | Default 
+ ---- | ----------- | ---- | -------- | ------- 
+ threeWayMergePatch | The strategy of the resource. | [threeWayMergePatch](#threewaymergepatch) | true |  
+
+
+##### threeWayMergePatch
+
+ Name | Description | Type | Required | Default 
+ ---- | ----------- | ---- | -------- | ------- 
+ enabled | The strategy to get or apply the resource. | bool | false | true 
+ annotationPrefix | The annotation prefix to use for the three way merge patch. | string | false | resource 
+
+
+### *Returns*
+
+ Name | Description | Type | Required | Default 
+ ---- | ----------- | ---- | -------- | ------- 
+ \- |  | {} | true |  
+## #Get
+
+
+### *Params*
+
+ Name | Description | Type | Required | Default 
+ ---- | ----------- | ---- | -------- | ------- 
+ cluster | The cluster to use. | string | true |  
+ resource | The resource to get or apply. | map[string]_ | true |  
+ options | The options to get or apply. | [options](#options) | true |  
+
+
+#### options
+
+ Name | Description | Type | Required | Default 
+ ---- | ----------- | ---- | -------- | ------- 
+ threeWayMergePatch | The strategy of the resource. | [threeWayMergePatch](#threewaymergepatch) | true |  
+
+
+##### threeWayMergePatch
+
+ Name | Description | Type | Required | Default 
+ ---- | ----------- | ---- | -------- | ------- 
+ enabled | The strategy to get or apply the resource. | bool | false | true 
+ annotationPrefix | The annotation prefix to use for the three way merge patch. | string | false | resource 
+
+
+### *Returns*
+
+ Name | Description | Type | Required | Default 
+ ---- | ----------- | ---- | -------- | ------- 
+ \- |  | {} | true |  
+## #List
+
+
+### *Params*
+
+ Name | Description | Type | Required | Default 
+ ---- | ----------- | ---- | -------- | ------- 
+ cluster | The cluster to use. | string | true |  
+ filter | The filter to list the resources. | [filter](#filter) | false |  
+ resource | The resource to list. | map[string]_ | true |  
+
+
+#### filter
+
+ Name | Description | Type | Required | Default 
+ ---- | ----------- | ---- | -------- | ------- 
+ namespace | The namespace to list the resources. | string | false |  
+ matchingLabels | The label selector to filter the resources. | map[string]string | false |  
+
+
+### *Returns*
+
+ Name | Description | Type | Required | Default 
+ ---- | ----------- | ---- | -------- | ------- 
+ \- |  | {} | true |  
+## #Patch
+
+
+### *Params*
+
+ Name | Description | Type | Required | Default 
+ ---- | ----------- | ---- | -------- | ------- 
+ cluster | The cluster to use. | string | true |  
+ resource | The resource to patch. | map[string]_ | true |  
+ patch | The patch to be applied to the resource with kubernetes patch. | [patch](#patch) | true |  
+
+
+#### patch
+
+ Name | Description | Type | Required | Default 
+ ---- | ----------- | ---- | -------- | ------- 
+ type | The type of patch being provided. | "merge" or "json" or "strategic" | true |  
+ data |  | _ | true |  
+
+
+### *Returns*
+
+ Name | Description | Type | Required | Default 
+ ---- | ----------- | ---- | -------- | ------- 
+ \- |  | {} | true |  
+------
+
@@ -0,0 +1,125 @@
+/*
+ Copyright 2023 The KubeVela Authors.
+
+ 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 docgen
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"io"
+	"strings"
+	"sync"
+
+	"cuelang.org/go/cue"
+	"cuelang.org/go/cue/cuecontext"
+	"golang.org/x/sync/errgroup"
+)
+
+// GenerateProvidersMarkdown generates markdown documentation for providers.
+func GenerateProvidersMarkdown(ctx context.Context, providers []io.Reader, w io.Writer) error {
+	docs := make([]string, len(providers))
+	mu := &sync.Mutex{}
+	wg, _ := errgroup.WithContext(ctx)
+
+	for i, provider := range providers {
+		i, provider := i, provider
+		wg.Go(func() error {
+			doc := bytes.NewBuffer(nil)
+
+			if err := GenerateProviderMarkdown(provider, doc); err != nil {
+				return err
+			}
+
+			mu.Lock()
+			docs[i] = doc.String() // stable order
+			mu.Unlock()
+
+			return nil
+		})
+	}
+
+	if err := wg.Wait(); err != nil {
+		return err
+	}
+
+	_, err := w.Write([]byte(strings.Join(docs, "\n")))
+	return err
+}
+
+// GenerateProviderMarkdown generates markdown documentation for a provider.
+func GenerateProviderMarkdown(provider io.Reader, w io.Writer) error {
+	const (
+		providerKey = "#provider"
+		paramsKey   = "$params"
+		returnsKey  = "$returns"
+	)
+
+	c := cuecontext.New()
+
+	content, err := io.ReadAll(provider)
+	if err != nil {
+		return fmt.Errorf("failed to read provider file: %w", err)
+	}
+
+	v := c.CompileBytes(content)
+	if v.Err() != nil {
+		return fmt.Errorf("failed to compile provider file: %w", v.Err())
+	}
+
+	// iter provider methods
+	iter, err := v.Fields(cue.Definitions(true))
+	if err != nil {
+		return fmt.Errorf("failed to get definition iterator: %w", err)
+	}
+
+	docs, ref, pkg := bytes.NewBuffer(nil), MarkdownReference{}, ""
+	for iter.Next() {
+		item := iter.Value()
+
+		// get package name. TODO(iyear): more elegant
+		if pkg == "" {
+			t, err := item.LookupPath(cue.ParsePath(providerKey)).String()
+			if err != nil {
+				return err
+			}
+			pkg = t
+		}
+
+		// header
+		docs.WriteString(fmt.Sprintf("## %s\n", iter.Label()))
+
+		doc, _, err := ref.parseParameters("", item.LookupPath(cue.ParsePath(paramsKey)), "*Params*", 0, true)
+		if err != nil {
+			return err
+		}
+		docs.WriteString(doc)
+
+		doc, _, err = ref.parseParameters("", item.LookupPath(cue.ParsePath(returnsKey)), "*Returns*", 0, true)
+		if err != nil {
+			return err
+		}
+		docs.WriteString(doc)
+	}
+
+	doc := bytes.NewBuffer(nil)
+	doc.WriteString(fmt.Sprintf("# %s\n\n", pkg)) // package name header
+	doc.Write(docs.Bytes())
+	doc.WriteString("------\n\n") // footer
+
+	_, err = w.Write(doc.Bytes())
+	return err
+}
@@ -0,0 +1,50 @@
+/*
+ Copyright 2023 The KubeVela Authors.
+
+ 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 docgen
+
+import (
+	"bytes"
+	"context"
+	"io"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestGenerateProvidersMarkdown(t *testing.T) {
+	// depends on cuegen testdata
+	path := "../cuegen/generators/provider/testdata"
+
+	src, err := os.ReadFile(filepath.Join(path, "valid.cue"))
+	require.NoError(t, err)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	got := bytes.NewBuffer(nil)
+	err = GenerateProvidersMarkdown(ctx, []io.Reader{bytes.NewBuffer(src)}, got)
+	require.NoError(t, err)
+
+	expected, err := os.ReadFile(filepath.Join(path, "valid.md"))
+	require.NoError(t, err)
+
+	assert.Equal(t, string(expected), got.String())
+}