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.

cli/cli.go

@@ -123,6 +123,8 @@ type Args struct {
 
 	FirstbootCmd *FirstbootArgs `arg:"subcommand:firstboot" help:"run some tasks on first boot"`
 
+	DocsCmd *DocsGenerateArgs `arg:"subcommand:docs" help:"generate documentation"`
+
 	// This never runs, it gets preempted in the real main() function.
 	// XXX: Can we do it nicely with the new arg parser? can it ignore all args?
 	EtcdCmd *EtcdArgs `arg:"subcommand:etcd" help:"run standalone etcd"`
@@ -167,6 +169,10 @@ func (obj *Args) Run(ctx context.Context, data *cliUtil.Data) (bool, error) {
 		return cmd.Run(ctx, data)
 	}
 
+	if cmd := obj.DocsCmd; cmd != nil {
+		return cmd.Run(ctx, data)
+	}
+
 	// NOTE: we could return true, fmt.Errorf("...") if more than one did
 	return false, nil // nobody activated
 }

cli/docs.go

@@ -0,0 +1,150 @@
+// Mgmt
+// Copyright (C) 2013-2024+ James Shubin and the project contributors
+// Written by James Shubin <james@shubin.ca> and the project contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+//
+// Additional permission under GNU GPL version 3 section 7
+//
+// If you modify this program, or any covered work, by linking or combining it
+// with embedded mcl code and modules (and that the embedded mcl code and
+// modules which link with this program, contain a copy of their source code in
+// the authoritative form) containing parts covered by the terms of any other
+// license, the licensors of this program grant you additional permission to
+// convey the resulting work. Furthermore, the licensors of this program grant
+// the original author, James Shubin, additional permission to update this
+// additional permission if he deems it necessary to achieve the goals of this
+// additional permission.
+
+package cli
+
+import (
+	"context"
+	"os"
+	"os/signal"
+	"sync"
+	"syscall"
+
+	cliUtil "github.com/purpleidea/mgmt/cli/util"
+	"github.com/purpleidea/mgmt/docs"
+)
+
+// DocsGenerateArgs is the CLI parsing structure and type of the parsed result.
+// This particular one contains all the common flags for the `docs generate`
+// subcommand.
+type DocsGenerateArgs struct {
+	docs.Config // embedded config (can't be a pointer) https://github.com/alexflint/go-arg/issues/240
+
+	DocsGenerate *cliUtil.DocsGenerateArgs `arg:"subcommand:generate" help:"generate documentation"`
+}
+
+// Run executes the correct subcommand. It errors if there's ever an error. It
+// returns true if we did activate one of the subcommands. It returns false if
+// we did not. This information is used so that the top-level parser can return
+// usage or help information if no subcommand activates. This particular Run is
+// the run for the main `docs` subcommand.
+func (obj *DocsGenerateArgs) Run(ctx context.Context, data *cliUtil.Data) (bool, error) {
+	ctx, cancel := context.WithCancel(ctx)
+	defer cancel()
+
+	var name string
+	var args interface{}
+	if cmd := obj.DocsGenerate; cmd != nil {
+		name = cliUtil.LookupSubcommand(obj, cmd) // "generate"
+		args = cmd
+	}
+	_ = name
+
+	Logf := func(format string, v ...interface{}) {
+		// Don't block this globally...
+		//if !data.Flags.Debug {
+		//	return
+		//}
+		data.Flags.Logf("main: "+format, v...)
+	}
+
+	var api docs.API
+
+	if cmd := obj.DocsGenerate; cmd != nil {
+		api = &docs.Generate{
+			DocsGenerateArgs: args.(*cliUtil.DocsGenerateArgs),
+			Config:           obj.Config,
+			Program:          data.Program,
+			Version:          data.Version,
+			Debug:            data.Flags.Debug,
+			Logf:             Logf,
+		}
+	}
+
+	if api == nil {
+		return false, nil // nothing found (display help!)
+	}
+
+	// We don't use these for the setup command in normal operation.
+	if data.Flags.Debug {
+		cliUtil.Hello(data.Program, data.Version, data.Flags) // say hello!
+		defer Logf("goodbye!")
+	}
+
+	// install the exit signal handler
+	wg := &sync.WaitGroup{}
+	defer wg.Wait()
+	exit := make(chan struct{})
+	defer close(exit)
+	wg.Add(1)
+	go func() {
+		defer cancel()
+		defer wg.Done()
+		// must have buffer for max number of signals
+		signals := make(chan os.Signal, 3+1) // 3 * ^C + 1 * SIGTERM
+		signal.Notify(signals, os.Interrupt) // catch ^C
+		//signal.Notify(signals, os.Kill) // catch signals
+		signal.Notify(signals, syscall.SIGTERM)
+		var count uint8
+		for {
+			select {
+			case sig := <-signals: // any signal will do
+				if sig != os.Interrupt {
+					data.Flags.Logf("interrupted by signal")
+					return
+				}
+
+				switch count {
+				case 0:
+					data.Flags.Logf("interrupted by ^C")
+					cancel()
+				case 1:
+					data.Flags.Logf("interrupted by ^C (fast pause)")
+					cancel()
+				case 2:
+					data.Flags.Logf("interrupted by ^C (hard interrupt)")
+					cancel()
+				}
+				count++
+
+			case <-exit:
+				return
+			}
+		}
+	}()
+
+	if err := api.Main(ctx); err != nil {
+		if data.Flags.Debug {
+			data.Flags.Logf("main: %+v", err)
+		}
+		return false, err
+	}
+
+	return true, nil
+}

cli/util/args.go

@@ -187,3 +187,12 @@ type FirstbootStartArgs struct {
 	DoneDir      string `arg:"--done-dir" help:"dir to move done scripts to"`
 	LoggingDir   string `arg:"--logging-dir" help:"directory to store logs in"`
 }
+
+// DocsGenerateArgs is the docgen utility CLI parsing structure and type of the
+// parsed result.
+type DocsGenerateArgs struct {
+	Output      string `arg:"--output" help:"output path to write to"`
+	RootDir     string `arg:"--root-dir" help:"path to mgmt source dir"`
+	NoResources bool   `arg:"--no-resources" help:"skip resource doc generation"`
+	NoFunctions bool   `arg:"--no-functions" help:"skip function doc generation"`
+}