Move docgen from gunk

All logic moved from gunk; common logic for both docgen and scopegen moved to
github.com/gunk/plugin

.gitignore

@@ -0,0 +1,2 @@
+docgen
+.DS_Store

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Gunk Project
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,55 @@
+# Docgen
+
+Docgen is a protobuf generator, generating markdown documentation. It is designed to be used with gunk, but can work separately, outside of gunk.
+
+For now, it goes through the same gunk package used
+in `gunk generate` command and generates a documentation markdown file `all.md`.
+
+## Installation
+
+Use the following command to install docgen:
+
+```sh
+$ go get -u github.com/gunk/docgen
+```
+
+This will place `docgen` in your `$GOBIN`
+
+## Usage
+
+Following describes usage with gunk. Outside of gunk, you will need to somehow plug in docgen to protoc.
+
+In your `.gunkconfig` add the following:
+
+```ini
+[generate]
+command=docgen
+out=examples/util/v1/
+```
+
+### Code examples
+
+To generate code examples, add the following to the `.gunkconfig` docgen section:
+
+```ini
+lang=go
+```
+
+Then add your `*.go` files near your gunk files. The examples files must be
+named according to the gunk method you want to showcase.
+
+Example:
+
+```go
+// UpdateAccount updates an account.
+UpdateAccount(UpdateAccountRequest)
+
+// DeleteAccount deletes an account.
+DeleteAccount(DeleteAccountRequest)
+```
+
+You should have `update_account.go` and `delete_account.go`.
+
+## Tests
+
+Tests are a separate module in `tests`, because they require gunk; while the main module does not.

docgen.go

@@ -0,0 +1,124 @@
+package main
+
+import (
+	"bytes"
+	"fmt"
+	"io/ioutil"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+
+	"github.com/Kunde21/markdownfmt/v2/markdownfmt"
+	"github.com/gunk/docgen/generate"
+	"github.com/gunk/docgen/parser"
+	"github.com/gunk/plugin"
+	"google.golang.org/protobuf/proto"
+	"google.golang.org/protobuf/types/pluginpb"
+)
+
+const modeAppend = "append"
+
+func main() {
+	plugin.RunMain(new(docPlugin))
+}
+
+type docPlugin struct{}
+
+func (p *docPlugin) Generate(req *pluginpb.CodeGeneratorRequest) (*pluginpb.CodeGeneratorResponse, error) {
+	var (
+		lang            []string
+		mode, dir       string
+		customHeaderIds generate.CustomHeaderIdsOpt
+		onlyExternal    parser.OnlyExternalOpt
+	)
+	if param := req.GetParameter(); param != "" {
+		ps := strings.Split(param, ",")
+		for _, p := range ps {
+			s := strings.Split(p, "=")
+			if len(s) != 2 {
+				return nil, fmt.Errorf("could not parse parameter: %s", p)
+			}
+			k, v := s[0], s[1]
+			switch k {
+			case "lang":
+				lang = append(lang, v)
+			case "mode":
+				if v != modeAppend {
+					return nil, fmt.Errorf("unknown mode: %s", v)
+				}
+				mode = v
+			case "out":
+				dir = v
+			case "custom-header-ids":
+				boolVal, err := strconv.ParseBool(v)
+				if err != nil {
+					return nil, err
+				}
+				if boolVal {
+					customHeaderIds = generate.CustomHeaderIdsOptEnabled
+				}
+			case "only_external":
+				boolVal, err := strconv.ParseBool(v)
+				if err != nil {
+					return nil, err
+				}
+				if boolVal {
+					onlyExternal = parser.OnlyExternalEnabled
+				}
+			default:
+				return nil, fmt.Errorf("unknown parameter: %s", k)
+			}
+		}
+	}
+	// find the source by looping through the protofiles and finding the one
+	// that matches the FileToGenerate
+	var source *parser.FileDescWrapper
+	for _, f := range req.GetProtoFile() {
+		if strings.Contains(f.GetName(), "all.proto") {
+			for _, fileToGenerate := range req.FileToGenerate {
+				if fileToGenerate == f.GetName() {
+					source = &parser.FileDescWrapper{FileDescriptorProto: f}
+					break
+				}
+			}
+		}
+	}
+	if source == nil {
+		return nil, fmt.Errorf("no file to generate")
+	}
+	base := filepath.Join(filepath.Dir(source.GetName()))
+	source.DependencyMap = parser.GenerateDependencyMap(source.FileDescriptorProto, req.GetProtoFile())
+	var buf bytes.Buffer
+	err := generate.Run(&buf, source, lang, customHeaderIds, onlyExternal)
+	if err != nil {
+		// file does not include a service -> just don't do anything
+		if err == generate.ErrNoServices {
+			return &pluginpb.CodeGeneratorResponse{
+				File: []*pluginpb.CodeGeneratorResponse_File{},
+			}, nil
+		}
+		return nil, fmt.Errorf("failed markdown generation: %v", err)
+	}
+
+	if mode == modeAppend {
+		// Load content from existing all.md
+		e, err := ioutil.ReadFile(filepath.Join(dir, "all.md"))
+		if err != nil && !os.IsNotExist(err) {
+			return nil, err
+		}
+		buf = *bytes.NewBuffer(append(e, buf.Bytes()...))
+	}
+	formatted, err := markdownfmt.Process("", buf.Bytes())
+	if err != nil {
+		return nil, err
+	}
+	return &pluginpb.CodeGeneratorResponse{
+		File: []*pluginpb.CodeGeneratorResponse_File{
+			{
+				Name:    proto.String(filepath.Join(base, "all.md")),
+				Content: proto.String(string(formatted)),
+			},
+		},
+	}, nil
+}

generate/generate.go

@@ -0,0 +1,63 @@
+package generate
+
+import (
+	"fmt"
+	"io"
+	"strings"
+	"text/template"
+
+	"github.com/gunk/docgen/parser"
+	"github.com/gunk/docgen/templates"
+)
+
+var ErrNoServices = fmt.Errorf("file has no services")
+
+type CustomHeaderIdsOpt int
+
+const (
+	CustomHeaderIdsOptDisabled CustomHeaderIdsOpt = iota
+	CustomHeaderIdsOptEnabled
+)
+
+// Run generates a markdown file describing the API and a messages.pot
+// containing all sentences that need to be translated.
+func Run(w io.Writer, f *parser.FileDescWrapper, lang []string,
+	customHeaderIds CustomHeaderIdsOpt, onlyExternal parser.OnlyExternalOpt) error {
+	api, err := parser.ParseFile(f, onlyExternal)
+	if err != nil {
+		return err
+	}
+	if !api.HasServices() {
+		return ErrNoServices
+	}
+	if err := api.CheckSwagger(); err != nil {
+		name := ""
+		if f.Name != nil {
+			name = *f.Name
+		}
+		return fmt.Errorf("swagger error in file %s: %w", name, err)
+	}
+
+	tpl := template.Must(template.New("doc").
+		Funcs(template.FuncMap{
+			"CustomHeaderId": func(txt ...string) string {
+				if customHeaderIds != CustomHeaderIdsOptEnabled {
+					return ""
+				}
+				return fmt.Sprintf("{#%s}", strings.Join(txt, ""))
+			},
+			"GetText": func(txt string) string {
+				return txt
+			},
+			"AddSnippet": func(name string) (string, error) {
+				return addSnippet(name, lang)
+			},
+			"mdType": func(txt string) string {
+				return strings.ReplaceAll(txt, "[", "\\[")
+			},
+		}).Parse(templates.API))
+	if err := tpl.Execute(w, api); err != nil {
+		return err
+	}
+	return nil
+}

generate/snippets.go

@@ -0,0 +1,72 @@
+package generate
+
+import (
+	"bytes"
+	"fmt"
+	"io/ioutil"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/kenshaw/snaker"
+)
+
+var codeTags = map[string]string{
+	"sh":  "shell",
+	"cpp": "c++",
+}
+
+func getGlob(name string) ([]string, error) {
+	var res []string
+	err := filepath.Walk(".",
+		func(path string, info os.FileInfo, err error) error {
+			if err != nil {
+				return err
+			}
+			if strings.HasPrefix(info.Name(), snaker.CamelToSnake(name)+".") {
+				res = append(res, path)
+			}
+
+			return nil
+		})
+	return res, err
+}
+
+func addSnippet(name string, langs []string) (string, error) {
+	matches, err := getGlob(name)
+	if err != nil {
+		return "", err
+	}
+	var res bytes.Buffer
+	for _, ext := range langs {
+		ext = strings.TrimSpace(ext)
+	MATCHES:
+		for _, file := range matches {
+			// node, err := ci.createNode(v, ext, ignoreExt)
+			tag := strings.TrimPrefix(filepath.Ext(file), ".")
+			if tag != ext {
+				continue MATCHES
+			}
+			if _, ok := codeTags[tag]; ok {
+				tag = codeTags[tag]
+			}
+			inject, err := ioutil.ReadFile(file)
+			if err != nil {
+				return "", fmt.Errorf("read code file %s: %w", file, err)
+			}
+			if tag != "md" {
+				// fake source here
+				source := "```" + tag + "\n"
+				source += string(inject)
+				if inject[len(inject)-1] != '\n' {
+					source += "\n"
+				}
+				source += "```"
+				inject = []byte(source)
+			}
+			res.Write(inject)
+			res.WriteString("\n\n")
+		}
+	}
+	return res.String(), nil
+}

go.mod

@@ -0,0 +1,12 @@
+module github.com/gunk/docgen
+
+go 1.16
+
+require (
+	github.com/Kunde21/markdownfmt/v2 v2.1.0
+	github.com/grpc-ecosystem/grpc-gateway/v2 v2.6.0
+	github.com/gunk/plugin v1.0.1
+	github.com/kenshaw/snaker v0.1.6
+	google.golang.org/genproto v0.0.0-20210909211513-a8c4777a87af
+	google.golang.org/protobuf v1.27.1
+)