This is an automated email from the ASF dual-hosted git repository. liujiapeng pushed a commit to branch generate-doc-tools in repository https://gitbox.apache.org/repos/asf/skywalking-satellite.git
commit db3fd761f46ccf3f8b03ce61b06f194a8b9321bf Author: Evan <[email protected]> AuthorDate: Tue Jan 12 22:48:01 2021 +0800 add plugin doc generator --- Makefile | 1 + cmd/command.go | 19 ++++--- cmd/main.go | 1 + internal/pkg/plugin/registry.go | 10 ++-- internal/satellite/tools/generate_plugin_doc.go | 67 +++++++++++++++++++++++++ plugins/fallbacker/timer/timer_fallbacker.go | 2 +- plugins/queue/mmap/queue.go | 2 +- 7 files changed, 87 insertions(+), 15 deletions(-) diff --git a/Makefile b/Makefile index 097c632..739cd83 100644 --- a/Makefile +++ b/Makefile @@ -86,6 +86,7 @@ build: deps linux darwin check: $(MAKE) clean $(GO) mod tidy &> /dev/null + /bin/sh ./bin/skywalking-satellite-latest-linux-amd64 docs @if [ ! -z "`git status -s |grep -v 'go.mod\|go.sum'`" ]; then \ echo "Following files are not consistent with CI:"; \ git status -s |grep -v 'go.mod\|go.sum'; \ diff --git a/cmd/command.go b/cmd/command.go index 0fe3c18..e8c3f0b 100644 --- a/cmd/command.go +++ b/cmd/command.go @@ -22,6 +22,7 @@ import ( "github.com/apache/skywalking-satellite/internal/satellite/boot" "github.com/apache/skywalking-satellite/internal/satellite/config" + "github.com/apache/skywalking-satellite/internal/satellite/tools" ) var ( @@ -37,15 +38,17 @@ var ( }, }, Action: func(c *cli.Context) error { - - cfg := loadConfig(c) + configPath := c.String("config") + cfg := config.Load(configPath) return boot.Start(cfg) }, } -) -func loadConfig(c *cli.Context) *config.SatelliteConfig { - configPath := c.String("config") - cfg := config.Load(configPath) - return cfg -} + cmdDocs = cli.Command{ + Name: "docs", + Usage: "generate satellite plugin docs", + Action: func(c *cli.Context) error { + return tools.GeneratePluginDoc() + }, + } +) diff --git a/cmd/main.go b/cmd/main.go index 0b51788..cbe819c 100644 --- a/cmd/main.go +++ b/cmd/main.go @@ -36,6 +36,7 @@ func main() { app.Description = "A lightweight collector/sidecar could be deployed closing to the target monitored system, to collect metrics, traces, and logs." app.Commands = []*cli.Command{ &cmdStart, + &cmdDocs, } app.Action = cli.ShowAppHelp _ = app.Run(os.Args) diff --git a/internal/pkg/plugin/registry.go b/internal/pkg/plugin/registry.go index edd6d11..cd6ffc9 100644 --- a/internal/pkg/plugin/registry.go +++ b/internal/pkg/plugin/registry.go @@ -30,16 +30,16 @@ import ( // the global plugin registry var ( - reg map[reflect.Type]map[string]reflect.Value + Reg map[reflect.Type]map[string]reflect.Value ) func init() { - reg = make(map[reflect.Type]map[string]reflect.Value) + Reg = make(map[reflect.Type]map[string]reflect.Value) } // RegisterPluginCategory register the RegInfo to the global type registry. func RegisterPluginCategory(pluginType reflect.Type) { - reg[pluginType] = map[string]reflect.Value{} + Reg[pluginType] = map[string]reflect.Value{} } // RegisterPlugin registers the pluginType as plugin. @@ -47,7 +47,7 @@ func RegisterPluginCategory(pluginType reflect.Type) { func RegisterPlugin(plugin Plugin) { v := reflect.ValueOf(plugin) success := false - for pCategory, pReg := range reg { + for pCategory, pReg := range Reg { if v.Type().Implements(pCategory) { pReg[plugin.Name()] = v log.Logger.Infof("register %s %s successfully", plugin.Name(), v.Type().String()) @@ -62,7 +62,7 @@ func RegisterPlugin(plugin Plugin) { // Get an initialized specific plugin according to the pluginCategory and config. func Get(category reflect.Type, cfg Config) Plugin { pluginName := nameFinder(cfg) - value, ok := reg[category][pluginName] + value, ok := Reg[category][pluginName] if !ok { panic(fmt.Errorf("cannot find %s plugin, and the category of plugin is %s", pluginName, category)) } diff --git a/internal/satellite/tools/generate_plugin_doc.go b/internal/satellite/tools/generate_plugin_doc.go new file mode 100644 index 0000000..5a2f481 --- /dev/null +++ b/internal/satellite/tools/generate_plugin_doc.go @@ -0,0 +1,67 @@ +// 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" + + "github.com/apache/skywalking-satellite/internal/pkg/log" + "github.com/apache/skywalking-satellite/internal/pkg/plugin" + "github.com/apache/skywalking-satellite/plugins" +) + +const ( + docDir = "docs" + docPath = docDir + "/plugin-description.md" +) + +func GeneratePluginDoc() error { + log.Init(&log.LoggerConfig{}) + plugins.RegisterPlugins() + doc := "" + const topLevel, SecondLevel, thirdLevel, LF, codeQuote = "# ", "## ", "### ", "\n", "```" + const descStr, confStr = "description", "defaultConfig" + for category, mapping := range plugin.Reg { + for name := range mapping { + p := plugin.Get(category, plugin.Config{plugin.NameField: name}) + doc += topLevel + category.String() + LF + doc += SecondLevel + name + LF + doc += thirdLevel + descStr + LF + codeQuote + p.Description() + codeQuote + LF + doc += thirdLevel + confStr + LF + codeQuote + p.DefaultConfig() + codeQuote + LF + } + } + + if err := createDir(docDir); err != nil { + return fmt.Errorf("the docs dir contains error: %v", err) + } + if err := ioutil.WriteFile(docPath, []byte(doc), os.ModePerm); err != nil { + return fmt.Errorf("cannot init the plugin doc: %v", err) + } + log.Logger.Info("Successfully generate documentation!") + return nil +} + +func createDir(path string) error { + fileInfo, err := os.Stat(path) + if os.IsNotExist(err) || fileInfo.Size() == 0 { + return os.Mkdir(docDir, os.ModePerm) + } + return err +} diff --git a/plugins/fallbacker/timer/timer_fallbacker.go b/plugins/fallbacker/timer/timer_fallbacker.go index 8398098..324f4b0 100644 --- a/plugins/fallbacker/timer/timer_fallbacker.go +++ b/plugins/fallbacker/timer/timer_fallbacker.go @@ -38,7 +38,7 @@ func (t *Fallbacker) Name() string { } func (t *Fallbacker) Description() string { - return "this is a timer trigger when forward fails." + return "this is a timer fallback trigger when forward fails." } func (t *Fallbacker) DefaultConfig() string { diff --git a/plugins/queue/mmap/queue.go b/plugins/queue/mmap/queue.go index 98f85c7..22b76b0 100644 --- a/plugins/queue/mmap/queue.go +++ b/plugins/queue/mmap/queue.go @@ -79,7 +79,7 @@ func (q *Queue) Name() string { } func (q *Queue) Description() string { - return "this is a mmap queue" + return "this is a memory mapped queue to provide the persistent storage." } func (q *Queue) DefaultConfig() string {
