WriteChunks: write all chunks before checking insertion status

CHANGES.md

@@ -1,5 +1,9 @@
 This file describes changes in the AutoDoc package.
 
+## unreleased
+  - Fix a spurious "chunk ... was defined but never inserted" warning for
+    chunks that are only inserted from within the body of another chunk
+
 ## 2026.06.30
   - Fix a regression in `.autodoc` parsing where Markdown-style headings
     and AutoDoc commands were interpreted inside XML CDATA blocks instead

gap/DocumentationTree.gi

@@ -479,6 +479,29 @@ BindGlobal( "WriteChunks",
     chunks_stream := AUTODOC_OutputTextFile( path_to_xmlfiles, filename );
     chunk_names := RecNames( tree!.chunks );
 
+    # Write out every chunk first. Writing a chunk whose body contains a
+    # nested @InsertChunk marks the inserted chunk as inserted, so all chunk
+    # bodies must be written before we can decide which chunks were never
+    # inserted -- otherwise a chunk used only from within a later-written
+    # chunk is spuriously flagged, depending on iteration order.
+    for current_chunk_name in chunk_names do
+        current_chunk := tree!.chunks.( current_chunk_name );
+        AppendTo( chunks_stream, "<#GAPDoc Label=\"", current_chunk_name, "\">\n" );
+        if IsBound( current_chunk!.content ) then
+            AUTODOC_WriteDocumentationListWithSource(
+                current_chunk!.content,
+                current_chunk!.content_source_positions,
+                chunks_stream
+            );
+        fi;
+        AppendTo( chunks_stream, "\n<#/GAPDoc>\n" );
+    od;
+
+    CloseStream( chunks_stream );
+
+    # Now that every insertion (including those nested inside other chunks)
+    # has been resolved, warn about chunks that are defined but never inserted,
+    # or inserted but never defined.
     for current_chunk_name in chunk_names do
         current_chunk := tree!.chunks.( current_chunk_name );
         if current_chunk!.is_defined = true and current_chunk!.is_inserted = false then
@@ -498,19 +521,8 @@ BindGlobal( "WriteChunks",
                 " was inserted but never defined"
             );
         fi;
-        AppendTo( chunks_stream, "<#GAPDoc Label=\"", current_chunk_name, "\">\n" );
-        if IsBound( current_chunk!.content ) then
-            AUTODOC_WriteDocumentationListWithSource(
-                current_chunk!.content,
-                current_chunk!.content_source_positions,
-                chunks_stream
-            );
-        fi;
-        AppendTo( chunks_stream, "\n<#/GAPDoc>\n" );
     od;
 
-    CloseStream( chunks_stream );
-
 end );
 
 ##

tst/misc.tst

@@ -325,6 +325,26 @@ gap> WriteDocumentation(tree3, Directory(tmpdir));
 gap> RemoveDirectoryRecursively(tmpdir);
 true
 
+#
+# do not warn about a chunk that is only inserted from within another chunk,
+# regardless of the order in which the chunks were defined
+#
+gap> tmpdir := Filename(DirectoryTemporary(), "autodoc-nestedchunk-test");;
+gap> if IsDirectoryPath(tmpdir) then RemoveDirectoryRecursively(tmpdir); fi;
+gap> AUTODOC_CreateDirIfMissing(tmpdir);
+true
+gap> tree4 := DocumentationTree();;
+gap> inner := DocumentationChunk(tree4, "Inner");;
+gap> inner!.is_defined := true;;
+gap> Add(inner!.content, "Some text");;
+gap> outer := DocumentationChunk(tree4, "Outer");;
+gap> outer!.is_defined := true;;
+gap> outer!.is_inserted := true;;
+gap> Add(outer!.content, inner);;
+gap> WriteDocumentation(tree4, Directory(tmpdir));
+gap> RemoveDirectoryRecursively(tmpdir);
+true
+
 #
 # mixed explicit and implicit chapter info with grouped declarations
 # see <https://github.com/gap-packages/AutoDoc/issues/279>