You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@skywalking.apache.org by wu...@apache.org on 2021/06/04 11:03:48 UTC
[skywalking-satellite] branch main updated: Support generate plugin
list index config in menu file (#49)
This is an automated email from the ASF dual-hosted git repository.
wusheng pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/skywalking-satellite.git
The following commit(s) were added to refs/heads/main by this push:
new aeed0be Support generate plugin list index config in menu file (#49)
aeed0be is described below
commit aeed0be9f0993bff00082d297bcc97921ff9f266
Author: mrproliu <74...@qq.com>
AuthorDate: Fri Jun 4 19:03:39 2021 +0800
Support generate plugin list index config in menu file (#49)
---
Makefile | 7 +-
README.md | 4 +-
cmd/command.go | 22 ++-
dist/LICENSE | 1 +
docs/en/guides/contribution/How-to-write-plugin.md | 2 +-
docs/menu.yml | 201 ++++++++++-----------
go.mod | 1 +
go.sum | 3 +
internal/satellite/tools/catalog.go | 101 +++++++++++
internal/satellite/tools/generate_plugin_doc.go | 51 +++++-
10 files changed, 277 insertions(+), 116 deletions(-)
diff --git a/Makefile b/Makefile
index c7e7162..8a67314 100644
--- a/Makefile
+++ b/Makefile
@@ -22,7 +22,9 @@ BINARY = skywalking-satellite
RELEASE_BIN = skywalking-satellite-$(VERSION)-bin
RELEASE_SRC = skywalking-satellite-$(VERSION)-src
-PLUGIN_DOC_DIR = docs/en/setup/plugins
+PLUGIN_DOC_BASE_DIR = docs
+PLUGIN_DOC_PLUGIN_DIR = /en/setup/plugins
+PLUGIN_DOC_MENU = /menu.yml
OSNAME := $(if $(findstring Darwin,$(shell uname)),darwin,linux)
@@ -56,8 +58,7 @@ deps: tools
.PHONY: gen-docs
gen-docs: build
- rm -rf $(PLUGIN_DOC_DIR)
- $(OUT_DIR)/$(BINARY)-$(VERSION)-$(OSNAME)-$(ARCH) docs --output=$(PLUGIN_DOC_DIR)
+ $(OUT_DIR)/$(BINARY)-$(VERSION)-$(OSNAME)-$(ARCH) docs -output=$(PLUGIN_DOC_BASE_DIR) -menu=$(PLUGIN_DOC_MENU) -plugins=$(PLUGIN_DOC_PLUGIN_DIR)
.PHONY: lint
lint: tools
diff --git a/README.md b/README.md
index d0b94e7..18d9f40 100644
--- a/README.md
+++ b/README.md
@@ -39,7 +39,9 @@ If you want to know more details about compiling, please read [the doc](./docs/e
| start | --config FILE, -c FILE | Load configuration from FILE. (default: "configs/satellite_config.yaml" or read value from *SATELLITE_CONFIG* env).|
| start | ---shutdown_hook_time TIME, -t TIME | The hook TIME for graceful shutdown, and the time unit is seconds. (default: "5" or read value from *SATELLITE_SHUTDOWN_HOOK_TIME* env).|
| start | --help, -h | Show help.|
-| docs | --output PATH, -o PATH | The output PATH for the plugin documentation. (default: "docs" or read value from *SATELLITE_DOC_PATH* env) |
+| docs | --output PATH, -o PATH | The document output root path. (default: "docs" or read value from *SATELLITE_DOC_PATH* env) |
+| docs | --menu PATH, -m PATH | The menu file path. (default: "/menu.yml" or read value from *SATELLITE_MENU_PATH* env) |
+| docs | --plugins PATH, -p PATH | The plugin list dir. (default: "/plugins" or read value from *SATELLITE_PLUGIN_PATH* env) |
| docs | --help, -h | Show help.|
diff --git a/cmd/command.go b/cmd/command.go
index 1be2ba2..e550a6c 100644
--- a/cmd/command.go
+++ b/cmd/command.go
@@ -62,14 +62,30 @@ var (
&cli.StringFlag{
Name: "output",
Aliases: []string{"o"},
- Usage: "The output `PATH` for the plugin documentation",
+ Usage: "The document output root path",
EnvVars: []string{"SATELLITE_DOC_PATH"},
Value: "docs",
},
+ &cli.StringFlag{
+ Name: "menu",
+ Aliases: []string{"m"},
+ Usage: "The menu file path",
+ EnvVars: []string{"SATELLITE_MENU_PATH"},
+ Value: "/menu.yml",
+ },
+ &cli.StringFlag{
+ Name: "plugins",
+ Aliases: []string{"p"},
+ Usage: "The plugin list dir",
+ EnvVars: []string{"SATELLITE_PLUGIN_PATH"},
+ Value: "/plugins",
+ },
},
Action: func(c *cli.Context) error {
- outputPath := c.String("output")
- return tools.GeneratePluginDoc(outputPath)
+ outputRootPath := c.String("output")
+ menuFilePath := c.String("menu")
+ pluginFilePath := c.String("plugins")
+ return tools.GeneratePluginDoc(outputRootPath, menuFilePath, pluginFilePath)
},
}
)
diff --git a/dist/LICENSE b/dist/LICENSE
index 8ecee2d..bcf17b2 100644
--- a/dist/LICENSE
+++ b/dist/LICENSE
@@ -216,6 +216,7 @@ The following components are provided under the Apache License. See project link
The text of each license is the standard Apache 2.0 license.
client_golang (prometheus) v1.9.0: https://github.com/prometheus/client_golang Apache 2.0
grpc-go (grpc) v1.36.1: https://github.com/grpc/grpc-go Apache 2.0
+ go-yaml (yaml) v3.0.0: https://github.com/go-yaml/yaml Apache 2.0
========================================================================
BSD licenses
diff --git a/docs/en/guides/contribution/How-to-write-plugin.md b/docs/en/guides/contribution/How-to-write-plugin.md
index 555f046..bdf43d1 100644
--- a/docs/en/guides/contribution/How-to-write-plugin.md
+++ b/docs/en/guides/contribution/How-to-write-plugin.md
@@ -35,7 +35,7 @@ Let's use memory-queue as an example of how to write a plugin.
3. Add [unit test](../test/How-to-unit-test.md).
4. Generate the plugin docs.
```shell script
-make check
+make gen-docs
```
diff --git a/docs/menu.yml b/docs/menu.yml
index 9e4454b..c72e0c0 100644
--- a/docs/menu.yml
+++ b/docs/menu.yml
@@ -14,109 +14,100 @@
# See the License for the specific language governing permissions and
# limitations under the License.
-
catalog:
- - name: "Welcome"
- path: "/readme"
- - name: "Concepts and Designs"
- path: "/en/concepts-and-designs/readme"
- catalog:
- - name: "What is SkyWalking Satellite?"
- catalog:
- - name: "Overview and Core concepts"
- path: "/en/concepts-and-designs/overview"
- - name: "Project Goals"
- path: "/en/concepts-and-designs/project-goals"
- - name: "Design"
- catalog:
- - name: "Module Design"
- path: "/en/concepts-and-designs/module_design"
- - name: "Plugin mechanism"
- path: "/en/concepts-and-designs/plugin_mechanism"
- - name: "Project Structure"
- path: "/en/concepts-and-designs/project_structue"
- - name: "The design of the memory mapped queue"
- path: "/en/concepts-and-designs/mmap-queue"
-
- - name: "Setup"
- path: "/en/setup/readme"
- catalog:
- - name: "Configuration"
- catalog:
- - name: "Common Configuration"
- path: "/en/setup/configuration/common"
- - name: "Sharing Configuration"
- path: "/en/setup/configuration/sharing-plugins"
- - name: "Pipe Configuration"
- path: "/en/setup/configuration/pipe-plugins"
- - name: "Override Configuration"
- path: "/en/setup/configuration/override-settings"
-
- - name: "Plugins"
- path: "/en/setup/plugins/plugin-list"
- catalog:
- - name: "client"
- catalog:
- - name: "grpc-client"
- path: "/en/setup/plugins/client_grpc-client"
- - name: "kafka-client"
- path: "/en/setup/plugins/client_kafka-client"
- - name: "fallbacker"
- catalog:
- - name: "none-fallbacker"
- path: "/en/setup/plugins/fallbacker_none-fallbacker"
- - name: "timer-fallbacker"
- path: "/en/setup/plugins/fallbacker_timer-fallbacker"
- - name: "forwarder"
- catalog:
- - name: "nativelog-grpc-forwarder"
- path: "/en/setup/plugins/forwarder_nativelog-grpc-forwarder"
- - name: "nativelog-kafka-forwarder"
- path: "/en/setup/plugins/forwarder_nativelog-kafka-forwarder"
- - name: "meter-grpc-forwarder"
- path: "/en/setup/plugins/forwarder_meter-grpc-forwarder"
- - name: "queue"
- catalog:
- - name: "memory-queue"
- path: "/en/setup/plugins/queue_memory-queue"
- - name: "mmap-queue"
- path: "/en/setup/plugins/queue_mmap-queue"
- - name: "receiver"
- catalog:
- - name: "grpc-nativelog-receiver"
- path: "/en/setup/plugins/receiver_grpc-nativelog-receiver"
- - name: "http-nativelog-receiver"
- path: "/en/setup/plugins/receiver_http-nativelog-receiver"
- - name: "server"
- catalog:
- - name: "grpc-server"
- path: "/en/setup/plugins/server_grpc-server"
- - name: "http-server"
- path: "/en/setup/plugins/server_http-server"
- - name: "prometheus-server"
- path: "/en/setup/plugins/server_http-server"
-
- - name: "Guides"
- path: "/en/guides/readme"
- catalog:
- - name: "Contribution"
- catalog:
- - name: "How to write a plugin"
- path: "/en/guides/contribution/How-to-write-plugin"
- - name: "How to release"
- path: "/en/guides/contribution/How-to-release"
- - name: "Test"
- catalog:
- - name: "How to do unit test"
- path: "/en/guides/test/How-to-unit-test"
- - name: "Compile"
- catalog:
- - name: "How to compile SkyWalking Satellite"
- path: "/en/guides/compile/How-to-compile"
- - name: "FAQs"
- path: "/en/FAQ/readme"
-
-
-
-
-
+ - name: Welcome
+ path: /readme
+ - name: Concepts and Designs
+ path: /en/concepts-and-designs/readme
+ catalog:
+ - name: What is SkyWalking Satellite?
+ catalog:
+ - name: Overview and Core concepts
+ path: /en/concepts-and-designs/overview
+ - name: Project Goals
+ path: /en/concepts-and-designs/project-goals
+ - name: Design
+ catalog:
+ - name: Module Design
+ path: /en/concepts-and-designs/module_design
+ - name: Plugin mechanism
+ path: /en/concepts-and-designs/plugin_mechanism
+ - name: Project Structure
+ path: /en/concepts-and-designs/project_structue
+ - name: The design of the memory mapped queue
+ path: /en/concepts-and-designs/mmap-queue
+ - name: Setup
+ path: /en/setup/readme
+ catalog:
+ - name: Configuration
+ catalog:
+ - name: Common Configuration
+ path: /en/setup/configuration/common
+ - name: Sharing Configuration
+ path: /en/setup/configuration/sharing-plugins
+ - name: Pipe Configuration
+ path: /en/setup/configuration/pipe-plugins
+ - name: Override Configuration
+ path: /en/setup/configuration/override-settings
+ - name: Plugins
+ path: /en/setup/plugins/plugin-list
+ catalog:
+ - name: client
+ catalog:
+ - name: grpc-client
+ path: /en/setup/plugins/client_grpc-client
+ - name: kafka-client
+ path: /en/setup/plugins/client_kafka-client
+ - name: fallbacker
+ catalog:
+ - name: none-fallbacker
+ path: /en/setup/plugins/fallbacker_none-fallbacker
+ - name: timer-fallbacker
+ path: /en/setup/plugins/fallbacker_timer-fallbacker
+ - name: forwarder
+ catalog:
+ - name: meter-grpc-forwarder
+ path: /en/setup/plugins/forwarder_meter-grpc-forwarder
+ - name: nativelog-grpc-forwarder
+ path: /en/setup/plugins/forwarder_nativelog-grpc-forwarder
+ - name: nativelog-kafka-forwarder
+ path: /en/setup/plugins/forwarder_nativelog-kafka-forwarder
+ - name: queue
+ catalog:
+ - name: memory-queue
+ path: /en/setup/plugins/queue_memory-queue
+ - name: mmap-queue
+ path: /en/setup/plugins/queue_mmap-queue
+ - name: receiver
+ catalog:
+ - name: grpc-nativelog-receiver
+ path: /en/setup/plugins/receiver_grpc-nativelog-receiver
+ - name: http-nativelog-receiver
+ path: /en/setup/plugins/receiver_http-nativelog-receiver
+ - name: server
+ catalog:
+ - name: grpc-server
+ path: /en/setup/plugins/server_grpc-server
+ - name: http-server
+ path: /en/setup/plugins/server_http-server
+ - name: prometheus-server
+ path: /en/setup/plugins/server_prometheus-server
+ - name: Guides
+ path: /en/guides/readme
+ catalog:
+ - name: Contribution
+ catalog:
+ - name: How to write a plugin
+ path: /en/guides/contribution/How-to-write-plugin
+ - name: How to release
+ path: /en/guides/contribution/How-to-release
+ - name: Test
+ catalog:
+ - name: How to do unit test
+ path: /en/guides/test/How-to-unit-test
+ - name: Compile
+ catalog:
+ - name: How to compile SkyWalking Satellite
+ path: /en/guides/compile/How-to-compile
+ - name: FAQs
+ path: /en/FAQ/readme
diff --git a/go.mod b/go.mod
index 8e5c460..0a04f50 100644
--- a/go.mod
+++ b/go.mod
@@ -15,5 +15,6 @@ require (
go.uber.org/automaxprocs v1.4.0
google.golang.org/grpc v1.38.0
google.golang.org/protobuf v1.26.0
+ gopkg.in/yaml.v3 v3.0.0-20210107192922-496545a6307b
skywalking.apache.org/repo/goapi v0.0.0-20210604033701-af17f1bab1a2
)
diff --git a/go.sum b/go.sum
index d93e612..7067c71 100644
--- a/go.sum
+++ b/go.sum
@@ -610,6 +610,8 @@ gopkg.in/yaml.v2 v2.3.0/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
gopkg.in/yaml.v3 v3.0.0-20200615113413-eeeca48fe776 h1:tQIYjPdBoyREyB9XMu+nnTclpTYkz2zFM+lzLJFO4gQ=
gopkg.in/yaml.v3 v3.0.0-20200615113413-eeeca48fe776/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.0-20210107192922-496545a6307b h1:h8qDotaEPuJATrMmW04NCwg7v22aHH28wwpauUhK9Oo=
+gopkg.in/yaml.v3 v3.0.0-20210107192922-496545a6307b/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
honnef.co/go/tools v0.0.0-20180728063816-88497007e858/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=
honnef.co/go/tools v0.0.0-20190102054323-c2f93a96b099/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=
honnef.co/go/tools v0.0.0-20190106161140-3f1c8253044a/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=
@@ -617,6 +619,7 @@ honnef.co/go/tools v0.0.0-20190418001031-e561f6794a2a/go.mod h1:rf3lG4BRIbNafJWh
honnef.co/go/tools v0.0.0-20190523083050-ea95bdfd59fc/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=
honnef.co/go/tools v0.0.1-2019.2.3/go.mod h1:a3bituU0lyd329TUQxRnasdCoJDkEUEAqEt0JzvZhAg=
rsc.io/binaryregexp v0.2.0/go.mod h1:qTv7/COck+e2FymRvadv62gMdZztPaShugOCi3I+8D8=
+sigs.k8s.io/yaml v1.1.0 h1:4A07+ZFc2wgJwo8YNlQpr1rVlgUDlxXHhPJciaPY5gs=
sigs.k8s.io/yaml v1.1.0/go.mod h1:UJmg0vDUVViEyp3mgSv9WPwZCDxu4rQW1olrI1uml+o=
skywalking.apache.org/repo/goapi v0.0.0-20210604033701-af17f1bab1a2 h1:jWagII79aT2DcR+evh2YpASfbTYcenbOqyQerswwA1k=
skywalking.apache.org/repo/goapi v0.0.0-20210604033701-af17f1bab1a2/go.mod h1:wm5inQxMxXggTPgEk1iTzZ7EqA/VqbsByywT1dWrCww=
diff --git a/internal/satellite/tools/catalog.go b/internal/satellite/tools/catalog.go
new file mode 100644
index 0000000..95808b5
--- /dev/null
+++ b/internal/satellite/tools/catalog.go
@@ -0,0 +1,101 @@
+// Licensed to Apache Software Foundation (ASF) under one or more contributor
+// license agreements. See the NOTICE file distributed with
+// this work for additional information regarding copyright
+// ownership. Apache Software Foundation (ASF) licenses this file to you 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 tools
+
+import (
+ "fmt"
+ "io/ioutil"
+ "os"
+
+ "gopkg.in/yaml.v3"
+)
+
+type Catalog struct {
+ Name string `yaml:"name,omitempty"`
+ Path string `yaml:"path,omitempty"`
+ Catalog []*Catalog `yaml:"catalog,omitempty"`
+}
+
+// LoadCatalog data from file
+func LoadCatalog(filename string) (*Catalog, error) {
+ bytes, err := ioutil.ReadFile(filename)
+ if err != nil {
+ return nil, fmt.Errorf("cannot read the menu file: %v", err)
+ }
+
+ catalog := Catalog{}
+ err = yaml.Unmarshal(bytes, &catalog)
+ if err != nil {
+ return nil, fmt.Errorf("cannot unmarshal menu file: %v", err)
+ }
+ return &catalog, nil
+}
+
+// Find Catalog by paths
+func (c *Catalog) Find(namePaths ...string) *Catalog {
+ if c.Catalog == nil {
+ return nil
+ }
+
+ childrens := c.Catalog
+ finded := c
+ for _, name := range namePaths {
+ finded = nil
+ for _, cc := range childrens {
+ if cc.Name == name {
+ finded = cc
+ break
+ }
+ }
+ if finded == nil {
+ return nil
+ }
+ childrens = finded.Catalog
+ }
+ return finded
+}
+
+func (c *Catalog) Save(filename string) error {
+ content := []byte(`# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you 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.
+
+`)
+
+ marshal, err := yaml.Marshal(c)
+ if err != nil {
+ return err
+ }
+
+ if err := ioutil.WriteFile(filename, append(content, marshal...), os.ModePerm); err != nil {
+ return fmt.Errorf("cannot write catalog: %v", err)
+ }
+ return nil
+}
diff --git a/internal/satellite/tools/generate_plugin_doc.go b/internal/satellite/tools/generate_plugin_doc.go
index 7b0d32c..6a2c068 100644
--- a/internal/satellite/tools/generate_plugin_doc.go
+++ b/internal/satellite/tools/generate_plugin_doc.go
@@ -39,14 +39,18 @@ const (
markdownSuffix = ".md"
)
-func GeneratePluginDoc(docDir string) error {
+func GeneratePluginDoc(outputRootPath, menuFilePath, pluginFilePath string) error {
log.Init(&log.LoggerConfig{})
plugins.RegisterPlugins()
- if err := createDir(docDir); err != nil {
+ pluginPath := fmt.Sprintf("%s%s", outputRootPath, pluginFilePath)
+ if err := createDir(pluginPath); err != nil {
return fmt.Errorf("create docs dir error: %v", err)
}
- if err := generatePluginListDoc(docDir, getSortedCategories()); err != nil {
+ if err := generatePluginListDoc(pluginPath, getSortedCategories()); err != nil {
+ return err
+ }
+ if err := updateMenuPluginListDoc(outputRootPath, menuFilePath, pluginFilePath, getSortedCategories()); err != nil {
return err
}
log.Logger.Info("Successfully generate documentation!")
@@ -65,6 +69,47 @@ func getSortedCategories() []reflect.Type {
return categories
}
+func updateMenuPluginListDoc(outputRootPath, menuFilePath, pluginFilePath string, categories []reflect.Type) error {
+ menuFile := fmt.Sprintf("%s%s", outputRootPath, menuFilePath)
+ menu, err := LoadCatalog(menuFile)
+ if err != nil {
+ return err
+ }
+
+ // find plugin Catalog
+ pluginCatalog := menu.Find("Setup", "Plugins")
+ if pluginCatalog == nil {
+ return fmt.Errorf("cannot find plugins Catalog")
+ }
+
+ // rebuild all plugins
+ var allPlugins []*Catalog
+ for _, category := range categories {
+ // plugin
+ implements := []*Catalog{}
+ curPlugin := &Catalog{
+ Name: strings.ToLower(category.Name()),
+ }
+
+ // all implements
+ pluginList := getPluginsByCategory(category)
+ for _, pluginName := range pluginList {
+ implements = append(implements, &Catalog{
+ Name: pluginName,
+ Path: strings.TrimRight(fmt.Sprintf("%s/%s", pluginFilePath, getPluginDocFileName(category, pluginName)), markdownSuffix),
+ })
+ }
+ curPlugin.Catalog = implements
+
+ if len(implements) > 0 {
+ allPlugins = append(allPlugins, curPlugin)
+ }
+ }
+ pluginCatalog.Catalog = allPlugins
+
+ return menu.Save(menuFile)
+}
+
func generatePluginListDoc(docDir string, categories []reflect.Type) error {
fileName := docDir + "/" + "plugin-list" + markdownSuffix
doc := topLevel + "Plugin List" + lf