Initial commit

.github/workflows/zz_generated.create_release_pr.yaml

@@ -176,7 +176,7 @@ jobs:
           # Check chart YAML.
           if [ -f "${chart_yaml}" ]
           then
-            # check if version in Chart.yaml is templated using architect
+            # check if version in Chart.yaml is schemadocsd using architect
             if [ $(grep -c "^version:.*\.Version.*$" "${chart_yaml}") = "0" ]; then
               yq -i '.version = "${{ needs.gather_facts.outputs.version }}"' "${chart_yaml}"
             fi

.gitignore

@@ -0,0 +1,8 @@
+.idea
+
+*.iml
+
+sample.json
+test_readme.md
+
+schemadocs

CHANGELOG.md

@@ -11,4 +11,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 
 
-[Unreleased]: https://github.com/giantswarm/REPOSITORY_NAME/tree/master
+[Unreleased]: https://github.com/giantswarm/schemadocs/tree/master

README.md

@@ -1,30 +1,14 @@
 [![CircleCI](https://circleci.com/gh/giantswarm/template.svg?style=shield)](https://circleci.com/gh/giantswarm/template)
 
-# REPOSITORY_NAME
+# schemadocs - the Giant Swarm JSON Schema docs generator 
 
-This is a template repository containing some basic files every repository
-needs.
+- Generates Markdown documentation from JSON schema files and injects it into text files
+- Validates generated Markdown documentation in text files and checks whether it is aligned with the supplied JSON schema file
 
-To use it just hit `Use this template` button or [this link][generate].
+## Usage
 
-Things to do with your newly created repo:
+```nohighlight
+schemadoc generate path/to/myschema.json
 
-1. Run`devctl replace -i "REPOSITORY_NAME" "$(basename $(git rev-parse
-   --show-toplevel))" --ignore '.git/**' '**'`.
-2. Run `devctl replace -i "template" "$(basename $(git rev-parse
-   --show-toplevel))" --ignore '.git/**' '**'`.
-3. Go to https://github.com/giantswarm/REPOSITORY_NAME/settings and make sure `Allow
-   merge commits` box is unchecked and `Automatically delete head branches` box
-   is checked.
-4. Go to https://github.com/giantswarm/REPOSITORY_NAME/settings/access and add
-   `giantswarm/bots` with `Write` access and `giantswarm/employees` with
-   `Admin` access.
-5. Add this repository to https://github.com/giantswarm/github.
-6. Create quay.io docker repository if needed.
-7. Add the project to the CircleCI:
-   https://circleci.com/setup-project/gh/giantswarm/REPOSITORY_NAME
-8. Change the badge (with style=shield):
-   https://circleci.com/gh/giantswarm/REPOSITORY_NAME.svg?style=shield&circle-token=TOKEN_FOR_PRIVATE_REPO
-   If this is a private repository token with scope `status` will be needed.
-
-[generate]: https://github.com/giantswarm/template/generate
+schemadoc validata --schema path/to/myschema.json path/to/text-file.md
+```

cmd/error.go

@@ -0,0 +1,21 @@
+package cmd
+
+import (
+	"github.com/giantswarm/microerror"
+)
+
+var invalidConfigError = &microerror.Error{
+	Kind: "invalidConfigError",
+}
+
+func isInvalidConfig(err error) bool {
+	return microerror.Cause(err) == invalidConfigError
+}
+
+var invalidFlagError = &microerror.Error{
+	Kind: "invalidFlagError",
+}
+
+func isInvalidFlag(err error) bool {
+	return microerror.Cause(err) == invalidFlagError
+}

cmd/flag.go

@@ -0,0 +1,16 @@
+package cmd
+
+import (
+	"github.com/spf13/cobra"
+)
+
+type flag struct {
+}
+
+func (f *flag) Init(cmd *cobra.Command) {
+
+}
+
+func (f *flag) Validate() error {
+	return nil
+}

cmd/generate/command.go

@@ -0,0 +1,46 @@
+package generate
+
+import (
+	"github.com/spf13/cobra"
+	"io"
+	"os"
+)
+
+const (
+	name        = "generate"
+	description = "Generate documentation from JSON schema"
+)
+
+type Config struct {
+	Stderr io.Writer
+	Stdout io.Writer
+}
+
+func New(config Config) (*cobra.Command, error) {
+	if config.Stderr == nil {
+		config.Stderr = os.Stderr
+	}
+	if config.Stdout == nil {
+		config.Stdout = os.Stdout
+	}
+
+	f := &flag{}
+
+	r := &runner{
+		flag:   f,
+		stderr: config.Stderr,
+		stdout: config.Stdout,
+	}
+
+	c := &cobra.Command{
+		Use:   name,
+		Short: description,
+		Long:  description,
+		RunE:  r.Run,
+		Args:  cobra.MinimumNArgs(1),
+	}
+
+	f.Init(c)
+
+	return c, nil
+}

cmd/generate/error.go

@@ -0,0 +1,19 @@
+package generate
+
+import "github.com/giantswarm/microerror"
+
+var invalidConfigError = &microerror.Error{
+	Kind: "invalidConfigError",
+}
+
+func isInvalidConfig(err error) bool {
+	return microerror.Cause(err) == invalidConfigError
+}
+
+var invalidFlagError = &microerror.Error{
+	Kind: "invalidFlagError",
+}
+
+func isInvalidFlag(err error) bool {
+	return microerror.Cause(err) == invalidFlagError
+}

cmd/generate/flag.go

@@ -0,0 +1,31 @@
+package generate
+
+import (
+	"github.com/giantswarm/microerror"
+	"github.com/spf13/cobra"
+)
+
+const (
+	flagReadme              = "readme"
+	flagDocPlaceholderStart = "doc-placeholder-start"
+	flagDocPlaceholderEnd   = "doc-placeholder-end"
+)
+
+type flag struct {
+	readme              string
+	docPlaceholderStart string
+	docPlaceholderEnd   string
+}
+
+func (f *flag) Init(cmd *cobra.Command) {
+	cmd.Flags().StringVar(&f.readme, flagReadme, "", "Path to file to output the generated documentation")
+	cmd.Flags().StringVar(&f.docPlaceholderStart, flagDocPlaceholderStart, "", "Placeholder string marking the start of the docs section in the output file")
+	cmd.Flags().StringVar(&f.docPlaceholderEnd, flagDocPlaceholderEnd, "", "Placeholder string marking the end of the docs section in the output file")
+}
+
+func (f *flag) Validate() error {
+	if (f.docPlaceholderStart == "") != (f.docPlaceholderEnd == "") {
+		return microerror.Maskf(invalidFlagError, "both --% and --S flags must be set to non-empty values", flagDocPlaceholderStart, flagDocPlaceholderEnd)
+	}
+	return nil
+}

cmd/generate/runner.go

@@ -0,0 +1,52 @@
+package generate
+
+import (
+	"fmt"
+	"github.com/giantswarm/microerror"
+	"github.com/giantswarm/schemadocs/pkg/cli"
+	"github.com/giantswarm/schemadocs/pkg/generate"
+	"github.com/giantswarm/schemadocs/pkg/readme"
+	"github.com/spf13/cobra"
+	"io"
+)
+
+type runner struct {
+	flag   *flag
+	stdout io.Writer
+	stderr io.Writer
+}
+
+func (r *runner) Run(cmd *cobra.Command, args []string) error {
+	err := r.run(cmd, args)
+	if err != nil {
+		writeErr := cli.WriteError(r.stderr, "Failed to generate documentation", err)
+		if writeErr != nil {
+			return writeErr
+		}
+	}
+	return err
+}
+
+func (r *runner) run(cmd *cobra.Command, args []string) error {
+	err := r.flag.Validate()
+	if err != nil {
+		return microerror.Mask(err)
+	}
+
+	docs, err := generate.Generate(args[0])
+	if err != nil {
+		return microerror.Mask(err)
+	}
+
+	readmeItem, err := readme.New(r.flag.readme, r.flag.docPlaceholderStart, r.flag.docPlaceholderEnd)
+	if err != nil {
+		return microerror.Mask(err)
+	}
+
+	err = readmeItem.WriteDocs(docs)
+	if err != nil {
+		return microerror.Mask(err)
+	}
+
+	return cli.WriteOutput(r.stdout, fmt.Sprintf("Successfully generated documentation from %s and stored it in %s", args[0], r.flag.readme))
+}

cmd/root.go

@@ -0,0 +1,84 @@
+package cmd
+
+import (
+	"github.com/giantswarm/microerror"
+	"github.com/giantswarm/schemadocs/cmd/generate"
+	"github.com/giantswarm/schemadocs/cmd/validate"
+	"github.com/giantswarm/schemadocs/pkg/project"
+	"github.com/spf13/cobra"
+	"io"
+	"os"
+)
+
+const (
+	name        = "schemadoc"
+	description = "Generator and validator of Markdown docs from JSON schema files in text files"
+)
+
+type Config struct {
+	Stdout io.Writer
+	Stderr io.Writer
+}
+
+func New(config Config) (*cobra.Command, error) {
+	if config.Stderr == nil {
+		config.Stderr = os.Stderr
+	}
+	if config.Stdout == nil {
+		config.Stdout = os.Stdout
+	}
+
+	var err error
+
+	f := &flag{}
+
+	r := &runner{
+		flag:   f,
+		stdout: config.Stdout,
+		stderr: config.Stderr,
+	}
+
+	c := &cobra.Command{
+		Use:          name,
+		Short:        description,
+		RunE:         r.Run,
+		SilenceUsage: true,
+		Version:      project.Version(),
+		CompletionOptions: cobra.CompletionOptions{
+			DisableDefaultCmd: true,
+		},
+	}
+
+	f.Init(c)
+
+	var generateCmd *cobra.Command
+	{
+		c := generate.Config{
+			Stderr: config.Stderr,
+			Stdout: config.Stdout,
+		}
+
+		generateCmd, err = generate.New(c)
+		if err != nil {
+			return nil, microerror.Mask(err)
+		}
+	}
+
+	var validateCmd *cobra.Command
+	{
+		c := validate.Config{
+			Stderr: config.Stderr,
+			Stdout: config.Stdout,
+		}
+
+		validateCmd, err = validate.New(c)
+		if err != nil {
+			return nil, microerror.Mask(err)
+		}
+	}
+
+	c.AddCommand(generateCmd)
+	c.AddCommand(validateCmd)
+
+	return c, nil
+}

cmd/runner.go

@@ -0,0 +1,29 @@
+package cmd
+
+import (
+	"github.com/giantswarm/microerror"
+	"github.com/giantswarm/micrologger"
+	"github.com/spf13/cobra"
+	"io"
+)
+
+type runner struct {
+	flag   *flag
+	logger micrologger.Logger
+	stdout io.Writer
+	stderr io.Writer
+}
+
+func (r *runner) Run(cmd *cobra.Command, args []string) error {
+	err := r.flag.Validate()
+	if err != nil {
+		return microerror.Mask(err)
+	}
+
+	err = cmd.Help()
+	if err != nil {
+		return microerror.Mask(err)
+	}
+
+	return nil
+}