From b5529b261604d476e70120a0634f0826188ecdd8 Mon Sep 17 00:00:00 2001
From: Puck Meerburg <puck@puckipedia.com>
Date: Mon, 23 Jun 2025 12:22:20 +0000
Subject: [PATCH] docs: autogenerate code part of table of contents

Change-Id: I6a6a6964ec580d2403029e21ce785da000830c3d
---
 docs/.gitignore                          |  2 +
 docs/docread/default.nix                 |  1 +
 docs/docread/docread.egg                 |  2 +-
 docs/docread/docread.scm                 | 50 ++++++++++++++++++++++--
 docs/modules/ROOT/nav.adoc               | 35 +----------------
 docs/modules/generated/pages/.gitkeep    |  0
 docs/modules/generated/partials/.gitkeep |  0
 7 files changed, 51 insertions(+), 39 deletions(-)
 create mode 100644 docs/modules/generated/pages/.gitkeep
 create mode 100644 docs/modules/generated/partials/.gitkeep

diff --git a/docs/.gitignore b/docs/.gitignore
index 4e71956..a221c57 100644
--- a/docs/.gitignore
+++ b/docs/.gitignore
@@ -2,3 +2,5 @@
 /node_modules
 /modules/generated/pages/*
 !/modules/generated/pages/.gitkeep
+/modules/generated/partials/*
+!/modules/generated/partials/.gitkeep
diff --git a/docs/docread/default.nix b/docs/docread/default.nix
index f57f8b7..129eadc 100644
--- a/docs/docread/default.nix
+++ b/docs/docread/default.nix
@@ -5,6 +5,7 @@ eggDerivation {
 
   buildInputs = with chickenPackages.chickenEggs; [
     r7rs
+    srfi-132
     (pkgs.callPackage ../../core {})
   ];
 }
diff --git a/docs/docread/docread.egg b/docs/docread/docread.egg
index 8eb4b38..1cd5fdd 100644
--- a/docs/docread/docread.egg
+++ b/docs/docread/docread.egg
@@ -1,7 +1,7 @@
 ((version "0.0.1")
  (synopsis "read doc comments")
  (author "puck")
- (dependencies r7rs zilch)
+ (dependencies r7rs srfi-132 zilch)
  (component-options 
   (csc-options "-X" "r7rs" "-R" "r7rs" "-optimize-level" "3"))
  (components
diff --git a/docs/docread/docread.scm b/docs/docread/docread.scm
index ed31120..e610749 100644
--- a/docs/docread/docread.scm
+++ b/docs/docread/docread.scm
@@ -1,4 +1,4 @@
-(import (scheme base) (scheme file) (scheme write) (chicken read-syntax) (chicken process-context) (chicken irregex) (chicken format) (chicken process) (chicken file) (zilch zexpr))
+(import (scheme base) (scheme file) (scheme write) (chicken read-syntax) (chicken process-context) (chicken irregex) (chicken format) (chicken process) (chicken file) (zilch zexpr) (srfi 132))
 
 ;; Return a string version of the passed-in val, but properly quoted as s-expression.
 (define (quotify val)
@@ -72,6 +72,35 @@
  (call-with-port (open-output-string)
   (lambda (p) (render-lambda-doc p doc) (get-output-string p))))
 
+(define table-of-contents
+ '(((zilch lang rust) . ())
+   ((zilch lang ninja) . ())
+   ((zilch lang go) . ())
+   ((zilch nix) . ())
+   ((zilch lib) . ())
+   ((zilch) . ())))
+
+; Returns whether `left` is a prefix of `right`.
+(define (is-prefix left right)
+  (define
+   res
+   (let loop ((left left) (right right))
+    (cond
+     ((and (null? left) (null? right)) #t)
+     ((null? left) #t)
+     ((null? right) #f)
+     ((equal? (car left) (car right)) (loop (cdr left) (cdr right)))
+     (else #f))))
+  res)
+
+(define (add-to-toc name path)
+  (let loop ((item table-of-contents))
+    (cond
+     ((null? item) (error "Unknown TOC root" name))
+     ((equal? name (caar item)) (set-cdr! (car item) (cons (sprintf "** xref:generated:~A[++~A++]\n" path name) (cdar item))))
+     ((is-prefix (caar item) name) (set-cdr! (car item) (cons (sprintf "*** xref:generated:~A[++~A++]\n" path name) (cdar item))))
+     (else (loop (cdr item))))))
+
 ;; Iterate over the contents of a define-library, and collect comments on certain defines.
 (define (parse-library-contents fname contents lib-comments)
     (define comments '())
@@ -141,10 +170,12 @@
                               (cdr j)))))
               contents)
 
-    (define out-path (string-append root "/docs/modules/generated/pages"))
     (define first #t)
-    (for-each (lambda (l) (set! out-path (string-append out-path (if first "/" ".") (symbol->string l))) (set! first #f)) (car contents))
-    (set! out-path (string-append out-path ".adoc"))
+    (define file-path "")
+    (for-each (lambda (l) (set! file-path (string-append file-path (if first "" ".") (symbol->string l))) (set! first #f)) (car contents))
+    (set! file-path (string-append file-path ".adoc"))
+    (define out-path (string-append root "/docs/modules/generated/pages/" file-path))
+    (add-to-toc (car contents) file-path)
 
     (define out-file (open-output-file out-path))
     ; Print out the comments
@@ -178,3 +209,14 @@
 
 
 (find-files root #:test ".*\\.(sld|scm)" #:action process-file)
+
+(call-with-output-file (string-append root "/docs/modules/generated/partials/nav.adoc")
+ (lambda (p)
+  (for-each
+   (lambda (chunk)
+    (define sorted (list-sort string<? (cdr chunk)))
+    (when (or (null? sorted) (not (string=? (string-copy (car sorted) 0 3) "** ")))
+     (fprintf p "** ++~A++\n" (car chunk)))
+    (for-each (lambda (line) (write-string line p)) sorted)
+    (write-string "\n" p))
+   (reverse table-of-contents))))
diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
index 966a367..585aba5 100644
--- a/docs/modules/ROOT/nav.adoc
+++ b/docs/modules/ROOT/nav.adoc
@@ -3,37 +3,4 @@
 * xref:zexp.adoc[]
 
 * Code
-** ++(zilch)++
-*** xref:generated:zilch.file.adoc[++(zilch file)++]
-*** xref:generated:zilch.magic.adoc[++(zilch magic)++]
-*** xref:generated:zilch.nixpkgs.adoc[++(zilch nixpkgs)++]
-*** xref:generated:zilch.semver.adoc[++(zilch semver)++]
-*** xref:generated:zilch.statusbar.adoc[++(zilch statusbar)++]
-*** xref:generated:zilch.vfs.adoc[++(zilch vfs)++]
-*** xref:generated:zilch.zexpr.adoc[++(zilch zexpr)++]
-
-** xref:generated:zilch.lang.go.adoc[++(zilch lang go)++]
-*** xref:generated:zilch.lang.go.core.adoc[++(zilch lang go core)++]
-*** xref:generated:zilch.lang.go.fetch.adoc[++(zilch lang go fetch)++]
-*** xref:generated:zilch.lang.go.mod.adoc[++(zilch lang go mod)++]
-*** xref:generated:zilch.lang.go.package.adoc[++(zilch lang go package)++]
-*** xref:generated:zilch.lang.go.stdlib.adoc[++(zilch lang go stdlib)++]
-*** xref:generated:zilch.lang.go.sum.adoc[++(zilch lang go sum)++]
-*** xref:generated:zilch.lang.go.version.adoc[++(zilch lang go version)++]
-*** xref:generated:zilch.lang.go.vfs.adoc[++(zilch lang go vfs)++]
-
-** xref:generated:zilch.lang.rust.adoc[++(zilch lang rust)++]
-*** xref:generated:zilch.lang.rust.build-script.adoc[++(zilch lang rust build-script)++]
-*** xref:generated:zilch.lang.rust.cargo.adoc[++(zilch lang rust cargo)++]
-*** xref:generated:zilch.lang.rust.cfg.adoc[++(zilch lang rust cfg)++]
-*** xref:generated:zilch.lang.rust.registry.adoc[++(zilch lang rust registry)++]
-*** xref:generated:zilch.lang.rust.resolver.adoc[++(zilch lang rust resolver)++]
-** ++(zilch lib)++
-*** xref:generated:zilch.lib.getopt.adoc[++(zilch lib getopt)++]
-*** xref:generated:zilch.lib.hash.adoc[++(zilch lib hash)++]
-** ++(zilch nix)++
-*** xref:generated:zilch.nix.binproto.adoc[++(zilch nix binproto)++]
-*** xref:generated:zilch.nix.daemon.adoc[++(zilch nix daemon)++]
-*** xref:generated:zilch.nix.drv.adoc[++(zilch nix drv)++]
-*** xref:generated:zilch.nix.hash.adoc[++(zilch nix hash)++]
-*** xref:generated:zilch.nix.path.adoc[++(zilch nix path)++]
+include::generated:partial$nav.adoc[]
diff --git a/docs/modules/generated/pages/.gitkeep b/docs/modules/generated/pages/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/docs/modules/generated/partials/.gitkeep b/docs/modules/generated/partials/.gitkeep
new file mode 100644
index 0000000..e69de29