docs: generate server options as list-table for stable diffs (#4426)

* docs: generate server options as list-table for stable diffs

The simple-table format pads every cell to the widest value in its
column, so a single new option with a long description rewrites the
entire table (as happened in #4420, where 2 new options produced a
142-line diff). A list-table has no cross-row alignment: adding an
option is always a 3-line diff. The rendered HTML is identical,
verified by diffing Sphinx output of both formats.

Also removes a stray debug println from the generator.

Assisted-by: AI

* build: add docs-docker Makefile target for containerized Sphinx builds

The docs/Dockerfile existed but nothing referenced it. The new target
builds the documentation without requiring Python/Sphinx on the host.

Assisted-by: AI

---------

Co-authored-by: Rein Krul <info@reinkrul.nl>

Author: stevenvegt

docs/generate_docs.go

@@ -178,7 +178,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
@@ -248,9 +247,10 @@ func generateRstTable(tableName, fileName string, values [][]rstValue) {
 		panic(err)
 	}
 	defer optionsFile.Close()
-	optionsFile.WriteString(fmt.Sprintf(".. table:: %s\n", tableName))
+	optionsFile.WriteString(fmt.Sprintf(".. list-table:: %s\n", tableName))
 	optionsFile.WriteString("    :widths: 20 30 50\n")
-	optionsFile.WriteString("    :class: options-table\n\n")
+	optionsFile.WriteString("    :class: options-table\n")
+	optionsFile.WriteString("    :header-rows: 1\n\n")
 	printRstTable(vals("Key", "Default", "Description"), values, optionsFile)
 	if err := optionsFile.Sync(); err != nil {
 		panic(err)

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"}},