doc: Create a blockreplace tool to update generated blocks in docs

We introduced a minor issue in #5757 that was causing the manpages to
be added every time we regenerate instead of replacing them. The
script was a bit unscrutable, and we do this block-replacement in
several places I thought it might be a good idea to have a dedicated
tool to do it.

This allows us to have simpler Makefiles whenever we update a
generated block inside another file. It's python, but does not have
dependencies :-)

Changelog-None

devtools/blockreplace.py

@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+
+# A rather simple script to replace a block of text, delimited by
+# markers, with new contents from stdin. Importantly the markers are
+# left in the file so future runs can update the file without
+# requiring a separate template. The markers are currently for
+# reStructuredText only, but more can be added.
+
+import argparse
+import os
+import sys
+import textwrap
+
+
+def replace(filename, blockname, content):
+    start = f".. block_start {blockname}"
+    stop = f".. block_end {blockname}"
+
+    tempfile = f"{filename}.tmp"
+
+    with open(filename, 'r') as i, open(tempfile, 'w') as o:
+        lines = i.readlines()
+        # Read lines up to the marker
+        while lines != []:
+            l = lines.pop(0)
+            o.write(l)
+            if l.strip() == start:
+                break
+
+        o.write(content)
+
+        # Skip lines until we get the end marker
+        while lines != []:
+            l = lines.pop(0)
+            if l.strip() == stop:
+                o.write(l)
+                break
+
+        # Now flush the rest of the file
+        for l in lines:
+            o.write(l)
+
+    # Move the temp file over the old one for an atomic replacement
+    os.rename(tempfile, filename)
+
+
+def main(args):
+    parser = argparse.ArgumentParser(
+        prog='blockreplace'
+    )
+    parser.add_argument('filename')
+    parser.add_argument('blockname')
+    parser.add_argument('--indent', dest="indent", default="")
+    args = parser.parse_args()
+    content = sys.stdin.read()
+    content = textwrap.indent(content, args.indent)
+
+    replace(args.filename, args.blockname, content)
+
+
+if __name__ == "__main__":
+    main(sys.argv)

doc/Makefile

@@ -196,4 +196,9 @@ doc-clean:
 	$(RM) doc/deployable-lightning.{aux,bbl,blg,dvi,log,out,tex}
 
 doc/index.rst: $(MANPAGES:=.md)
-	@$(call VERBOSE, "genidx $@",(grep -v "^   (reckless|lightning).*\.[0-9]\.md>$$" $@; for m in $$(cd doc && ls reckless.7.md lightningd*.[0-9].md lightning-*.[0-9].md); do echo "   $${m%.[0-9].md} <$$m>"; done |$(SORT)) > $@.tmp.$$$$ && mv $@.tmp.$$$$ $@)
+	@$(call VERBOSE, "genidx $@", \
+	  find doc -maxdepth 1 -name '*\.[0-9]\.md' | \
+	  cut -b 5- | LC_ALL=C sort | \
+	  sed 's/\(.*\)\.\(.*\).*\.md/\1 <\1.\2.md>/' | \
+	  python3 devtools/blockreplace.py doc/index.rst manpages --indent "   " \
+	)

doc/index.rst

@@ -29,6 +29,7 @@ Core Lightning Documentation
    :maxdepth: 1
    :caption: Manpages
 
+ .. block_start manpages
    lightning-addgossip <lightning-addgossip.7.md>
    lightning-autoclean-status <lightning-autoclean-status.7.md>
    lightning-batching <lightning-batching.7.md>
@@ -42,8 +43,8 @@ Core Lightning Documentation
    lightning-checkmessage <lightning-checkmessage.7.md>
    lightning-cli <lightning-cli.1.md>
    lightning-close <lightning-close.7.md>
-   lightning-commando <lightning-commando.7.md>
    lightning-commando-rune <lightning-commando-rune.7.md>
+   lightning-commando <lightning-commando.7.md>
    lightning-connect <lightning-connect.7.md>
    lightning-createinvoice <lightning-createinvoice.7.md>
    lightning-createonion <lightning-createonion.7.md>
@@ -126,7 +127,8 @@ Core Lightning Documentation
    lightning-waitinvoice <lightning-waitinvoice.7.md>
    lightning-waitsendpay <lightning-waitsendpay.7.md>
    lightning-withdraw <lightning-withdraw.7.md>
-   lightningd <lightningd.8.md>
    lightningd-config <lightningd-config.5.md>
    lightningd-rpc <lightningd-rpc.7.md>
+   lightningd <lightningd.8.md>
    reckless <reckless.7.md>
+.. block_end manpages