docs: generate server options as list-table for stable diffs (backport of #4426 to V6.2)

docs/generate_docs.go

@@ -190,7 +190,6 @@ func extractFlagsForEngine(flagSet *pflag.FlagSet, config interface{}, engineNam
 	}
 
 	flagSet.VisitAll(func(current *pflag.Flag) {
-		println(current.Name, engineName)
 		if current.Name == engineName ||
 			strings.HasPrefix(current.Name, engineName+".") {
 			// This flag belongs to this engine, so copy it and hide it in the input flag set
@@ -256,9 +255,10 @@ func normalizeDefaultValue(f *pflag.Flag) string {
 
 func renderRstTable(tableName string, values [][]rstValue) []byte {
 	buffer := new(bytes.Buffer)
-	fmt.Fprintf(buffer, ".. table:: %s\n", tableName)
+	fmt.Fprintf(buffer, ".. list-table:: %s\n", tableName)
 	buffer.WriteString("    :widths: 20 30 50\n")
-	buffer.WriteString("    :class: options-table\n\n")
+	buffer.WriteString("    :class: options-table\n")
+	buffer.WriteString("    :header-rows: 1\n\n")
 	printRstTable(vals("Key", "Default", "Description"), values, buffer)
 	return buffer.Bytes()
 }

docs/generate_docs_test.go

@@ -20,9 +20,36 @@ package main
 
 import (
 	"sort"
+	"strings"
 	"testing"
 )
 
+func TestPrintRstTable(t *testing.T) {
+	var buf strings.Builder
+	printRstTable(vals("Key", "Default", "Description"), [][]rstValue{
+		{{value: "HTTP", bold: true}},
+		vals("http.public.address", ":8080", "Public address"),
+		vals("cpuprofile", "", "CPU profile path"),
+	}, &buf)
+
+	expected := `    * - Key
+      - Default
+      - Description
+    * - **HTTP**
+      -
+      -
+    * - http.public.address
+      - \:8080
+      - Public address
+    * - cpuprofile
+      -
+      - CPU profile path
+`
+	if buf.String() != expected {
+		t.Errorf("unexpected list-table output:\ngot:\n%s\nwant:\n%s", buf.String(), expected)
+	}
+}
+
 func TestKeyList(t *testing.T) {
 	got := KeyList{
 		[]rstValue{{value: "storage.bbolt.backup.directory"}},

docs/generate_docs_uptodate_test.go

@@ -23,7 +23,7 @@ import (
 	"path/filepath"
 	"testing"
 
-	"github.com/nuts-foundation/nuts-node/cmd"
+	"github.com/nuts-foundation/nuts-node/v6/cmd"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )

docs/rst_table.go

@@ -24,58 +24,35 @@ import (
 	"strings"
 )
 
+// printRstTable renders the rows as the content of a list-table directive.
+// Each row is a self-contained block, so adding or changing a row never reformats
+// the other rows (unlike a simple table, where every cell is padded to the widest
+// value in its column and a single long value rewrites the entire table).
 func printRstTable(header []rstValue, values [][]rstValue, writer io.StringWriter) {
-	columnLengths := make([]int, len(header))
-	rows := make([][]rstValue, len(values)+1)
-	rows[0] = header
-	for i, row := range values {
-		rows[i+1] = row
+	printRow(header, len(header), writer)
+	for _, row := range values {
+		printRow(row, len(header), writer)
 	}
-	for _, row := range rows {
-		for i := 0; i < len(row); i++ {
-			columnLengths[i] = intMax(columnLengths[i], len(row[i].value))
-		}
-	}
-	dividers := []rstValue{
-		{value: strings.Repeat("=", columnLengths[0])},
-		{value: strings.Repeat("=", columnLengths[1])},
-		{value: strings.Repeat("=", columnLengths[2])},
-	}
-	printRow(dividers, columnLengths, writer)
-	printRow(rows[0], columnLengths, writer)
-	printRow(dividers, columnLengths, writer)
-	for i, row := range rows {
-		if i == 0 {
-			// Skip headers
-			continue
-		}
-		printRow(row, columnLengths, writer)
-	}
-	printRow(dividers, columnLengths, writer)
 }
 
-func printRow(values []rstValue, columnLengths []int, writer io.StringWriter) {
-	first := true
-	for i := 0; i < len(columnLengths); i++ {
-		if !first {
-			writer.WriteString("  ")
+func printRow(values []rstValue, columns int, writer io.StringWriter) {
+	for i := 0; i < columns; i++ {
+		prefix := "    * - "
+		if i > 0 {
+			prefix = "      - "
 		}
 		cell := rstValue{}
 		// Account for a row with less values than columns in the table
 		if i < len(values) {
 			cell = values[i]
 		}
-		writer.WriteString("    " + cell.render() + strings.Repeat(" ", columnLengths[i]-len(cell.value)))
-		first = false
-	}
-	writer.WriteString("\n")
-}
-
-func intMax(a int, b int) int {
-	if a > b {
-		return a
+		rendered := cell.render()
+		if rendered == "" {
+			// Avoid trailing whitespace on empty cells
+			prefix = strings.TrimRight(prefix, " ")
+		}
+		writer.WriteString(prefix + rendered + "\n")
 	}
-	return b
 }
 
 type rstValue struct {

makefile

@@ -102,6 +102,12 @@ cli-docs:
 	go run ./docs docs
 	rst_include include README_template.rst README.rst
 
+# Builds the Sphinx documentation in a container, so no Python/Sphinx tooling
+# is needed on the host. Output lands in docs/_build/html.
+docs-docker:
+	docker build -t nuts-node-docs docs/
+	docker run --rm -v ${DIR}/docs:/docs nuts-node-docs
+
 all-docs: cli-docs gen-diagrams
 
 fix-copyright: