Fix mixed explicit and implicit chapter contexts

CHANGES.md

@@ -2,6 +2,9 @@ This file describes changes in the AutoDoc package.
 
 2026.MM.DD
   - Greatly improve the package manual.
+  - Fix an unexpected and confusing error when mixing explicit
+    `@Chapter`/`@Section` markup in one file with auto-generated
+    chapter/section placement in another
   - Fix `InstallMethod` in first line of GAP source file leading to an error
   - Fix multiline `InstallMethod` parsing for filter lists and
     multiline `function(...)` argument lists

gap/DocumentationTree.gi

@@ -298,15 +298,15 @@ end );
 ##
 InstallMethod( DocumentationGroup, [ IsTreeForDocumentation, IsString, IsList ],
   function( tree, group_name, context )
-    local name, group;
+    local name, group, context_node;
 
     name := Concatenation( "GROUP_", group_name );
     if IsBound( tree!.nodes_by_label.( name ) ) then
         return tree!.nodes_by_label.( name );
     fi;
-    context := AUTODOC_LABEL_OF_CONTEXT( context );
+    context_node := StructurePartInTree( tree, context );
     group := DocumentationGroup( tree, group_name );
-    Add( tree!.nodes_by_label.( context ), group );
+    Add( context_node, group );
     group!.is_added := true;
     return group;
 end );
@@ -352,9 +352,8 @@ end );
 ##
 InstallMethod( Add, [ IsTreeForDocumentation, IsTreeForDocumentationNode, IsList ],
   function( tree, node, context )
-    local label, context_node;
-    label := AUTODOC_LABEL_OF_CONTEXT( context );
-    context_node := tree!.nodes_by_label.(label);
+    local context_node;
+    context_node := StructurePartInTree( tree, context );
     Add( context_node, node );
 end );
 

tst/misc.tst

@@ -151,5 +151,37 @@ gap> WriteDocumentation(tree3, Directory(tmpdir), 0);
 gap> RemoveDirectoryRecursively(tmpdir);
 true
 
+#
+# mixed explicit and implicit chapter info with grouped declarations
+# see <https://github.com/gap-packages/AutoDoc/issues/279>
+#
+gap> tmpdir := Filename(DirectoryTemporary(), "autodoc-mixed-context-test");;
+gap> if IsDirectoryPath(tmpdir) then RemoveDirectoryRecursively(tmpdir); fi;
+gap> AUTODOC_CreateDirIfMissing(tmpdir);
+true
+gap> tmpdir_obj := Directory(tmpdir);;
+gap> file1 := Filename(tmpdir_obj, "explicit.gd");;
+gap> stream := OutputTextFile(file1, false);;
+gap> AppendTo(stream, "#! @Chapter Explicit\n");;
+gap> AppendTo(stream, "#! @Section Intro\n");;
+gap> CloseStream(stream);
+gap> file2 := Filename(tmpdir_obj, "implicit.gd");;
+gap> stream := OutputTextFile(file2, false);;
+gap> AppendTo(stream, "#! @BeginGroup grouped\n");;
+gap> AppendTo(stream, "DeclareOperation( \"MixedOp\", [ IsObject ] );\n");;
+gap> CloseStream(stream);
+gap> tree4 := DocumentationTree();;
+gap> AutoDoc_Parser_ReadFiles([file1, file2], tree4, CreateDefaultChapterData("Pkg"));
+gap> auto_section := SectionInTree(tree4,
+>     "Pkg_automatic_generated_documentation",
+>     "Pkg_automatic_generated_documentation_of_methods");;
+gap> group := auto_section!.content[1];;
+gap> Label(group);
+"GROUP_grouped"
+gap> group!.content[1]!.name;
+"MixedOp"
+gap> RemoveDirectoryRecursively(tmpdir);
+true
+
 #
 gap> STOP_TEST( "misc.tst" );