fix and improve docs alias handling (closes #7)

xrstf · Dec 21, 2023 · 2387c48 · 2387c48
1 parent e84576d
commit 2387c48
Show file tree

Hide file tree

Showing 4 changed files with 30 additions and 4 deletions.
diff --git a/cmd/rudi/docs/data.go b/cmd/rudi/docs/data.go
@@ -13,6 +13,15 @@ import (
 	"go.xrstf.de/rudi/pkg/docs"
 )
 
+var Aliases = map[string]string{
+	// math module
+
+	"+": "add",
+	"-": "sub",
+	"*": "mult",
+	"/": "div",
+}
+
 //go:embed data/*
 var embeddedFS embed.FS
 
@@ -49,6 +58,11 @@ func RenderFile(filename string, painter PainterFunc) (string, error) {
 }
 
 func ReadFunction(funcName string) (string, error) {
+	realName, ok := Aliases[funcName]
+	if ok {
+		funcName = realName
+	}
+
 	return ReadFile(fmt.Sprintf("functions/%s.md", docs.Normalize(funcName)))
 }
 

diff --git a/hack/docs-prerender/main.go b/hack/docs-prerender/main.go
@@ -14,6 +14,7 @@ import (
 	"strings"
 
 	"go.xrstf.de/rudi/cmd/rudi/batteries"
+	rudidocs "go.xrstf.de/rudi/cmd/rudi/docs"
 	"go.xrstf.de/rudi/hack/docs-prerender/ansidoc"
 	"go.xrstf.de/rudi/pkg/docs"
 )
@@ -131,6 +132,11 @@ func dumpModules(mods []docs.Module, library string, wipe bool) {
 		}
 
 		for funcName := range mod.Functions {
+			// ignore aliases (mostly math aliases like "+" or "/")
+			if _, ok := rudidocs.Aliases[funcName]; ok {
+				continue
+			}
+
 			doc, err := mod.Documentation.Documentation(funcName)
 			if err != nil {
 				log.Printf("Warning: failed to get docs for %s/%s: %v", mod.Name, funcName, err)

diff --git a/hack/docs-toc/toc-library.go b/hack/docs-toc/toc-library.go
@@ -8,6 +8,7 @@ import (
 	"sort"
 	"strings"
 
+	rudidocs "go.xrstf.de/rudi/cmd/rudi/docs"
 	"go.xrstf.de/rudi/pkg/docs"
 )
 
@@ -20,8 +21,9 @@ func renderLibraryTOC(lib []docs.Module, linkPrefix string) string {
 
 		functions := []string{}
 		for funcName := range module.Functions {
-			// Hack: ignore math function aliases
-			if funcName == "+" || funcName == "-" || funcName == "*" || funcName == "/" {
+			// Hack: ignore aliases, mostly because the math functions have names
+			// that are incompatible with the filesystem (cannot have a "/.md" file).
+			if _, exists := rudidocs.Aliases[funcName]; exists {
 				continue
 			}
 
@@ -53,8 +55,9 @@ func renderHelpLibraryTOC(lib []docs.Module) string {
 
 		functions := []string{}
 		for funcName := range module.Functions {
-			// Hack: ignore math function aliases
-			if funcName == "+" || funcName == "-" || funcName == "*" || funcName == "/" {
+			// Hack: ignore aliases, mostly because the math functions have names
+			// that are incompatible with the filesystem (cannot have a "/.md" file).
+			if _, exists := rudidocs.Aliases[funcName]; exists {
 				continue
 			}
 

diff --git a/pkg/builtin/math/functions.go b/pkg/builtin/math/functions.go
@@ -18,6 +18,9 @@ var (
 	divideRudiFunction   = functions.NewBuilder(numberDivFunction).WithDescription("returns arg1 / arg2 / .. / argN (always a floating point division, regardless of arguments)").Build()
 
 	Functions = types.Functions{
+		// These are the main functions, but within the documentation these are
+		// considered to be aliases because their names cannot be used in Markdown
+		// filenames.
 		"+": addRudiFunction,
 		"-": subRudiFunction,
 		"*": multiplyRudiFunction,