From dacb29622f96c9128b263f19d106d9f01d7b1999 Mon Sep 17 00:00:00 2001 From: Max Horn Date: Tue, 3 Mar 2026 18:11:37 +0100 Subject: [PATCH 1/2] Fix mixed explicit and implicit chapter contexts Create missing chapter and section nodes lazily when grouped items are inserted so mixed explicit and auto-generated layouts do not crash. Fixes #279. Co-authored-by: Codex --- CHANGES.md | 2 ++ gap/DocumentationTree.gi | 11 +++++------ tst/misc.tst | 32 ++++++++++++++++++++++++++++++++ 3 files changed, 39 insertions(+), 6 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index b0793be8..c1c07138 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -2,6 +2,8 @@ This file describes changes in the AutoDoc package. 2026.MM.DD - Greatly improve the package manual. + - Fix a crash 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 diff --git a/gap/DocumentationTree.gi b/gap/DocumentationTree.gi index 7154199c..95e43931 100644 --- a/gap/DocumentationTree.gi +++ b/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 ); diff --git a/tst/misc.tst b/tst/misc.tst index e5685a75..bfd3d71e 100644 --- a/tst/misc.tst +++ b/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 +# +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" ); From d4ca386d2c3f4741972836837c0fbe5ce5e23b75 Mon Sep 17 00:00:00 2001 From: Max Horn Date: Tue, 3 Mar 2026 18:19:40 +0100 Subject: [PATCH 2/2] Apply suggestion from @fingolfin --- CHANGES.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index c1c07138..b880b99f 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -2,8 +2,9 @@ This file describes changes in the AutoDoc package. 2026.MM.DD - Greatly improve the package manual. - - Fix a crash when mixing explicit `@Chapter`/`@Section` markup in one - file with auto-generated chapter/section placement in another + - 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