docs: move reference into its own chapter

.github/workflows/doc.yml

@@ -45,7 +45,7 @@ jobs:
       - name: Build
         run: |
           cd docs
-          sed -i "s/canonifyURLs = true/canonifyURLs = false/g" config.toml
+          sed -i "s/canonifyURLs = true/canonifyURLs = false/g" hugo.toml
           export BRANCH_NAME=$(echo ${GITHUB_REF_NAME} | tr / -)
           echo "BRANCH_NAME=${BRANCH_NAME}" >> "$GITHUB_ENV"
           hugo --minify --baseURL https://${BRANCH_NAME}.resticprofile.pages.dev/

.github/workflows/release-doc.yml

@@ -1,6 +1,7 @@
 name: documentation
 
 on:
+  workflow_dispatch:
   push:
     tags:
       - 'v*'
@@ -61,7 +62,7 @@ jobs:
       - name: Build for pages.dev
         run: |
           cd docs
-          sed -i "s/canonifyURLs = true/canonifyURLs = false/g" config.toml
+          sed -i "s/canonifyURLs = true/canonifyURLs = false/g" hugo.toml
           hugo --minify --baseURL https://resticprofile.creativeprojects.tech/
 
       - name: Publish to pages.dev

.gitignore

@@ -30,6 +30,7 @@ status.json
 
 # documentation
 /docs/content/configuration/reference/index.md
+/docs/content/reference/**/*.md
 /docs/static/jsonschema
 /public
 .hugo_build.lock

Makefile

@@ -36,7 +36,7 @@ RESTIC_DIR=$(BUILD)restic-
 RESTIC_CMD=$(BUILD)restic-commands.json
 
 JSONSCHEMA_DIR=docs/static/jsonschema
-CONFIG_REFERENCE_DIR=docs/content/configuration/reference
+CONFIG_REFERENCE_DIR=docs/content/reference
 
 BUILD_DATE=`date`
 BUILD_COMMIT=`git rev-parse HEAD`
@@ -262,16 +262,16 @@ generate-jsonschema: build
 generate-config-reference: build
 	@echo "[*] $@"
 
-	META_TITLE="Reference" \
-	META_WEIGHT="50" \
+	META_TITLE="Resticprofile configuration reference" \
+	META_WEIGHT="6" \
 	LAYOUT_NO_HEADLINE="1" \
 	LAYOUT_HEADINGS_START="#" \
 	LAYOUT_NOTICE_START="{{% notice note %}}" \
 	LAYOUT_NOTICE_END="{{% /notice %}}" \
 	LAYOUT_HINT_START="{{% notice hint %}}" \
 	LAYOUT_HINT_END="{{% /notice %}}" \
 	LAYOUT_UPLINK="[go to top](#reference)" \
-	$(abspath $(BINARY)) generate --config-reference > $(CONFIG_REFERENCE_DIR)/index.md
+	$(abspath $(BINARY)) generate --config-reference --to $(CONFIG_REFERENCE_DIR)
 
 documentation: generate-jsonschema generate-config-reference
 	@echo "[*] $@"

commands.go

@@ -2,27 +2,22 @@ package main
 
 import (
 	"crypto/rand"
-	_ "embed"
 	"encoding/base64"
 	"errors"
 	"fmt"
 	"io"
 	"regexp"
 	"slices"
-	"sort"
 	"strconv"
 	"strings"
 
 	"github.com/creativeprojects/clog"
 	"github.com/creativeprojects/resticprofile/config"
-	"github.com/creativeprojects/resticprofile/config/jsonschema"
 	"github.com/creativeprojects/resticprofile/constants"
 	"github.com/creativeprojects/resticprofile/platform"
 	"github.com/creativeprojects/resticprofile/remote"
-	"github.com/creativeprojects/resticprofile/restic"
 	"github.com/creativeprojects/resticprofile/schedule"
 	"github.com/creativeprojects/resticprofile/term"
-	"github.com/creativeprojects/resticprofile/util/templates"
 	"github.com/creativeprojects/resticprofile/win"
 	"golang.org/x/exp/maps"
 )
@@ -201,97 +196,6 @@ func completeCommand(output io.Writer, ctx commandContext) error {
 	return nil
 }
 
-//go:embed contrib/completion/bash-completion.sh
-var bashCompletionScript string
-
-//go:embed contrib/completion/zsh-completion.sh
-var zshCompletionScript string
-
-func generateCommand(output io.Writer, ctx commandContext) (err error) {
-	args := ctx.request.arguments
-	// enforce no-log
-	logger := clog.GetDefaultLogger()
-	handler := logger.GetHandler()
-	logger.SetHandler(clog.NewDiscardHandler())
-
-	if slices.Contains(args, "--bash-completion") {
-		_, err = fmt.Fprintln(output, bashCompletionScript)
-	} else if slices.Contains(args, "--config-reference") {
-		err = generateConfigReference(output, args[slices.Index(args, "--config-reference")+1:])
-	} else if slices.Contains(args, "--json-schema") {
-		err = generateJsonSchema(output, args[slices.Index(args, "--json-schema")+1:])
-	} else if slices.Contains(args, "--random-key") {
-		ctx.flags.resticArgs = args[slices.Index(args, "--random-key"):]
-		err = randomKey(output, ctx)
-	} else if slices.Contains(args, "--zsh-completion") {
-		_, err = fmt.Fprintln(output, zshCompletionScript)
-	} else {
-		err = fmt.Errorf("nothing to generate for: %s", strings.Join(args, ", "))
-	}
-
-	if err != nil {
-		logger.SetHandler(handler)
-	}
-	return
-}
-
-//go:embed contrib/templates/config-reference.gomd
-var configReferenceTemplate string
-
-func generateConfigReference(output io.Writer, args []string) (err error) {
-	resticVersion := restic.AnyVersion
-	if slices.Contains(args, "--version") {
-		args = args[slices.Index(args, "--version"):]
-		if len(args) > 1 {
-			resticVersion = args[1]
-			args = args[2:]
-		}
-	}
-
-	data := config.NewTemplateInfoData(resticVersion)
-	tpl := templates.New("config-reference", data.GetFuncs())
-
-	if len(args) > 0 {
-		tpl, err = tpl.ParseFiles(args...)
-	} else {
-		tpl, err = tpl.Parse(configReferenceTemplate)
-	}
-
-	if err != nil {
-		err = fmt.Errorf("parsing failed: %w", err)
-	} else {
-		err = tpl.Execute(output, data)
-	}
-	return
-}
-
-func generateJsonSchema(output io.Writer, args []string) (err error) {
-	resticVersion := restic.AnyVersion
-	if slices.Contains(args, "--version") {
-		args = args[slices.Index(args, "--version"):]
-		if len(args) > 1 {
-			resticVersion = args[1]
-			args = args[2:]
-		}
-	}
-
-	version := config.Version02
-	if len(args) > 0 && args[0] == "v1" {
-		version = config.Version01
-	}
-
-	return jsonschema.WriteJsonSchema(version, resticVersion, output)
-}
-
-func sortedProfileKeys(data map[string]*config.Profile) []string {
-	keys := make([]string, 0, len(data))
-	for key := range data {
-		keys = append(keys, key)
-	}
-	sort.Strings(keys)
-	return keys
-}
-
 func showProfile(output io.Writer, ctx commandContext) error {
 	c := ctx.config
 	flags := ctx.flags

commands_display.go

@@ -322,6 +322,15 @@
 	out("\n")
 }
 
+func sortedProfileKeys(data map[string]*config.Profile) []string {
+	keys := make([]string, 0, len(data))
+	for key := range data {
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+	return keys
+}
+
 // lineLengthWriter limits the max line length, adding line breaks ('\n') as needed.
 // the writer detects the right most column (consecutive whitespace) and aligns content if possible.
 type lineLengthWriter struct {

commands_generate.go

@@ -0,0 +1,187 @@
+package main
+
+import (
+	"embed"
+	"fmt"
+	"io"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"slices"
+	"strings"
+	"text/template"
+
+	"github.com/creativeprojects/clog"
+	"github.com/creativeprojects/resticprofile/config"
+	"github.com/creativeprojects/resticprofile/config/jsonschema"
+	"github.com/creativeprojects/resticprofile/restic"
+	"github.com/creativeprojects/resticprofile/util/templates"
+)
+
+//go:embed contrib/completion/bash-completion.sh
+var bashCompletionScript string
+
+//go:embed contrib/completion/zsh-completion.sh
+var zshCompletionScript string
+
+func generateCommand(output io.Writer, ctx commandContext) (err error) {
+	args := ctx.request.arguments
+	// enforce no-log
+	logger := clog.GetDefaultLogger()
+	handler := logger.GetHandler()
+	logger.SetHandler(clog.NewDiscardHandler())
+
+	if slices.Contains(args, "--bash-completion") {
+		_, err = fmt.Fprintln(output, bashCompletionScript)
+	} else if slices.Contains(args, "--config-reference") {
+		err = generateConfigReference(output, args[slices.Index(args, "--config-reference")+1:])
+	} else if slices.Contains(args, "--json-schema") {
+		err = generateJsonSchema(output, args[slices.Index(args, "--json-schema")+1:])
+	} else if slices.Contains(args, "--random-key") {
+		ctx.flags.resticArgs = args[slices.Index(args, "--random-key"):]
+		err = randomKey(output, ctx)
+	} else if slices.Contains(args, "--zsh-completion") {
+		_, err = fmt.Fprintln(output, zshCompletionScript)
+	} else {
+		err = fmt.Errorf("nothing to generate for: %s", strings.Join(args, ", "))
+	}
+
+	if err != nil {
+		logger.SetHandler(handler)
+	}
+	return
+}
+
+//go:embed contrib/templates/*
+var configReferenceTemplates embed.FS
+
+func generateConfigReference(output io.Writer, args []string) error {
+	resticVersion := restic.AnyVersion
+	destination := "docs/content/reference"
+	if slices.Contains(args, "--version") {
+		args = args[slices.Index(args, "--version"):]
+		if len(args) > 1 {
+			resticVersion = args[1]
+			args = args[2:]
+		}
+	}
+	if slices.Contains(args, "--to") {
+		args = args[slices.Index(args, "--to"):]
+		if len(args) > 1 {
+			destination = args[1]
+			args = args[2:]
+		}
+	}
+
+	data := config.NewTemplateInfoData(resticVersion)
+	tpl := templates.New("config-reference", data.GetFuncs())
+	templates, err := fs.Sub(configReferenceTemplates, "contrib/templates")
+	if err != nil {
+		return fmt.Errorf("cannot load templates: %w", err)
+	}
+
+	if len(args) > 0 {
+		tpl, err = tpl.ParseFiles(args...)
+	} else {
+		tpl, err = tpl.ParseFS(templates, "*.gomd")
+	}
+
+	if err != nil {
+		return fmt.Errorf("parsing failed: %w", err)
+	}
+
+	staticPages := []struct {
+		templateName string
+		fileName     string
+	}{
+		{"reference.gomd", "_index.md"},
+		{"global.gomd", "global.md"},
+		{"profile.gomd", "profile/_index.md"},
+		{"nested.gomd", "nested/_index.md"},
+		{"groups.gomd", "groups.md"},
+		{"value-types.gomd", "value-types.md"},
+		{"json-schema.gomd", "json-schema.md"},
+	}
+
+	for _, staticPage := range staticPages {
+		fmt.Fprintf(output, "generating %s...\n", staticPage.templateName)
+		err = generatePage(tpl, data, filepath.Join(destination, staticPage.fileName), staticPage.templateName)
+		if err != nil {
+			return fmt.Errorf("unable to generate page %s: %w", staticPage.fileName, err)
+		}
+	}
+
+	weight := 1
+	for _, profileSection := range data.ProfileSections() {
+		fmt.Fprintf(output, "generating profile section %s (weight %d)...\n", profileSection.Name(), weight)
+		sectionData := SectionInfoData{
+			DefaultData: data.DefaultData,
+			Section:     profileSection,
+			Weight:      weight,
+		}
+		err = generatePage(tpl, sectionData, filepath.Join(destination, "profile", profileSection.Name()+".md"), "profile.sub-section.gomd")
+		if err != nil {
+			return fmt.Errorf("unable to generate profile section %s: %w", profileSection.Name(), err)
+		}
+		weight++
+	}
+
+	weight = 1
+	for _, nestedSection := range data.NestedSections() {
+		fmt.Fprintf(output, "generating nested section %s (weight %d)...\n", nestedSection.Name(), weight)
+		sectionData := SectionInfoData{
+			DefaultData: data.DefaultData,
+			Section:     nestedSection,
+			Weight:      weight,
+		}
+		err = generatePage(tpl, sectionData, filepath.Join(destination, "nested", nestedSection.Name()+".md"), "profile.nested-section.gomd")
+		if err != nil {
+			return fmt.Errorf("unable to generate nested section %s: %w", nestedSection.Name(), err)
+		}
+		weight++
+	}
+	return nil
+}
+
+func generatePage(tpl *template.Template, data any, fileName, templateName string) error {
+	err := os.MkdirAll(filepath.Dir(fileName), 0o755)
+	if err != nil {
+		return fmt.Errorf("cannot create directory: %w", err)
+	}
+	file, err := os.Create(fileName)
+	if err != nil {
+		return fmt.Errorf("cannot open file: %w", err)
+	}
+	defer file.Close()
+
+	err = tpl.ExecuteTemplate(file, templateName, data)
+	if err != nil {
+		return fmt.Errorf("cannot execute template: %w", err)
+	}
+	return nil
+}
+
+func generateJsonSchema(output io.Writer, args []string) (err error) {
+	resticVersion := restic.AnyVersion
+	if slices.Contains(args, "--version") {
+		args = args[slices.Index(args, "--version"):]
+		if len(args) > 1 {
+			resticVersion = args[1]
+			args = args[2:]
+		}
+	}
+
+	version := config.Version02
+	if len(args) > 0 && args[0] == "v1" {
+		version = config.Version01
+	}
+
+	return jsonschema.WriteJsonSchema(version, resticVersion, output)
+}
+
+// SectionInfoData is used as data for go templates that render profile section references
+type SectionInfoData struct {
+	templates.DefaultData
+	Section config.SectionInfo
+	Weight  int
+}