cli, docs: Add a docs command for doc generation

This took a lot longer than it looks to get right. It's not perfect, but
it now reliably generates documentation which we can put into gohugo.

engine/resources.go

@@ -33,8 +33,12 @@ import (
 	"context"
 	"encoding/gob"
 	"fmt"
+	"path/filepath"
+	"reflect"
+	"runtime"
 	"strings"
 
+	docsUtil "github.com/purpleidea/mgmt/docs/util"
 	"github.com/purpleidea/mgmt/engine/local"
 	"github.com/purpleidea/mgmt/pgraph"
 	"github.com/purpleidea/mgmt/util/errwrap"
@@ -42,6 +46,12 @@ import (
 	"gopkg.in/yaml.v2"
 )
 
+const (
+	// ResourcesRelDir is the path where the resources are kept, relative to
+	// the main source code root.
+	ResourcesRelDir = "engine/resources/"
+)
+
 // TODO: should each resource be a sub-package?
 var registeredResources = map[string]func() Res{}
 
@@ -57,6 +67,23 @@ func RegisterResource(kind string, fn func() Res) {
 	}
 	gob.Register(f)
 	registeredResources[kind] = fn
+
+	// Additional metadata for documentation generation!
+	_, filename, _, ok := runtime.Caller(1)
+	if !ok {
+		panic(fmt.Sprintf("could not locate resource filename for %s", kind))
+	}
+	sp := strings.Split(reflect.TypeOf(f).String(), ".")
+	if len(sp) != 2 {
+		panic(fmt.Sprintf("could not parse resource struct name for %s", kind))
+	}
+
+	if err := docsUtil.RegisterResource(kind, &docsUtil.Metadata{
+		Filename: filepath.Base(filename),
+		Typename: sp[1],
+	}); err != nil {
+		panic(fmt.Sprintf("could not register resource metadata for %s", kind))
+	}
 }
 
 // RegisteredResourcesNames returns the kind of the registered resources.

engine/resources/msg.go

@@ -52,9 +52,15 @@ type MsgRes struct {
 
 	init *engine.Init
 
-	Body     string            `lang:"body" yaml:"body"`
-	Priority string            `lang:"priority" yaml:"priority"`
-	Fields   map[string]string `lang:"fields" yaml:"fields"`
+	// Body is the body of the message to send.
+	Body string `lang:"body" yaml:"body"`
+
+	// Priority is the priority of the message. Currently this is one of:
+	// Emerg, Alert, Crit, Err, Warning, Notice, Info, Debug.
+	Priority string `lang:"priority" yaml:"priority"`
+
+	// Fields are the key/value pairs set in the journal if we are using it.
+	Fields map[string]string `lang:"fields" yaml:"fields"`
 
 	// Journal should be true to enable systemd journaled (journald) output.
 	Journal bool `lang:"journal" yaml:"journal"`

engine/resources/noop.go

@@ -49,7 +49,8 @@ type NoopRes struct {
 
 	init *engine.Init
 
-	Comment string `lang:"comment" yaml:"comment"` // extra field for example purposes
+	// Comment is a useless comment field that you can use however you like.
+	Comment string `lang:"comment" yaml:"comment"`
 }
 
 // Default returns some sensible defaults for this resource.

engine/resources/print.go

@@ -52,7 +52,9 @@ type PrintRes struct {
 
 	init *engine.Init
 
-	Msg string `lang:"msg" yaml:"msg"` // the message to display
+	// Msg is the message to display.
+	Msg string `lang:"msg" yaml:"msg"`
+
 	// RefreshOnly is an option that causes the message to be printed only
 	// when notified by another resource. When set to true, this resource
 	// cannot be autogrouped.

engine/resources/test.go

@@ -70,6 +70,7 @@ type TestRes struct {
 	Uint64 uint64 `lang:"uint64" yaml:"uint64"`
 
 	//Uintptr uintptr `lang:"uintptr" yaml:"uintptr"`
+
 	Byte byte `lang:"byte" yaml:"byte"` // alias for uint8
 	Rune rune `lang:"rune" yaml:"rune"` // alias for int32, represents a Unicode code point
 
@@ -84,7 +85,7 @@ type TestRes struct {
 	Int8Ptr   *int8   `lang:"int8ptr" yaml:"int8ptr"`
 	Uint8Ptr  *uint8  `lang:"uint8ptr" yaml:"uint8ptr"`
 
-	// probably makes no sense, but is legal
+	// Int8PtrPtrPtr probably makes no sense, but is legal.
 	Int8PtrPtrPtr ***int8 `lang:"int8ptrptrptr" yaml:"int8ptrptrptr"`
 
 	SliceString []string          `lang:"slicestring" yaml:"slicestring"`