Merge branch 'topic/merge_master_to_edge' into 'edge'

Reset edge to master

See merge request eng/ide/gnatdoc!181

Author: AnthonyLeonardoGracio

documentation/project_file.md

@@ -19,6 +19,11 @@ include any project files directly or undirectly used by the root project.
 Note, externally build library project files are excluded from the
 documentation generation unconditionally.
 
+## Image_Dirs
+
+List of directories (relative to directory of the root project file) to lookup
+for images referenced in the documentation.
+
 ## Output_Dir
 
 Allows to specify output directory for the generated documentation.

documentation/users_guide/backends.rst

@@ -46,6 +46,17 @@ Layout of the resources directory
     style documentation is specified)
 
 
+ODF
+===
+
+The ODF backend can be used to generate documentation in OpenDocument Format
+(ODF) format. The generated file can be opened by many office suites
+(Microsoft Word, LibreOffice Writer, etc) to apply different styles and print
+the documentation.
+
+Output can be customized by providing a custom
+*<resources_dir>/template/documentation.fodt* file.
+
 
 RST
 ===

documentation/users_guide/configuration.rst

@@ -69,3 +69,17 @@ and templates can be specified via the string attribute *Resources_Dir* of the
 
 Each backend has own conventions on the layout of the resources directory: see
 the documentation of the particular backend.
+
+
+Images directories
+------------------
+
+
+List of directories to lookup for image files referenced in the documentation
+can be defined with *Image_Dirs* attribute of the root project file::
+
+   package Documentation is
+      for Image_Dirs ("odf") use ("images");
+   end Documentation;
+
+By default paths are resolved relatively to the project file's root directory.

source/backend/markdown-blocks-visitors.adb

@@ -0,0 +1,85 @@
+--
+--  Copyright (C) 2025, AdaCore
+--
+--  SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+--
+
+with Markdown.Blocks.Indented_Code;
+with Markdown.Blocks.Lists;
+with Markdown.Blocks.Paragraphs;
+with Markdown.Block_Containers;
+
+package body Markdown.Blocks.Visitors is
+
+   procedure Visit_Block_Container
+     (Self      : in out Block_Iterator'Class;
+      Container : Markdown.Block_Containers.Block_Container'Class;
+      Visitor   : in out Block_Visitor'Class);
+
+   procedure Visit_List
+     (Self    : in out Block_Iterator'Class;
+      Block   : Markdown.Blocks.Lists.List'Class;
+      Visitor : in out Block_Visitor'Class);
+
+   -------------
+   -- Iterate --
+   -------------
+
+   procedure Iterate
+     (Self     : in out Block_Iterator'Class;
+      Document : Markdown.Documents.Document'Class;
+      Visitor  : in out Block_Visitor'Class) is
+   begin
+      Self.Visit_Block_Container (Document, Visitor);
+   end Iterate;
+
+   ---------------------------
+   -- Visit_Block_Container --
+   ---------------------------
+
+   procedure Visit_Block_Container
+     (Self      : in out Block_Iterator'Class;
+      Container : Markdown.Block_Containers.Block_Container'Class;
+      Visitor   : in out Block_Visitor'Class) is
+   begin
+      for Item of Container loop
+         if Item.Is_Paragraph then
+            Visitor.Enter_Paragraph (Item.To_Paragraph);
+            Visitor.Leave_Paragraph (Item.To_Paragraph);
+
+         elsif Item.Is_Indented_Code_Block then
+            Visitor.Enter_Indented_Code_Block (Item.To_Indented_Code_Block);
+            Visitor.Leave_Indented_Code_Block (Item.To_Indented_Code_Block);
+
+         elsif Item.Is_List then
+            Self.Visit_List (Item.To_List, Visitor);
+
+         else
+            raise Program_Error;
+         end if;
+      end loop;
+   end Visit_Block_Container;
+
+   ----------------
+   -- Visit_List --
+   ----------------
+
+   procedure Visit_List
+     (Self    : in out Block_Iterator'Class;
+      Block   : Markdown.Blocks.Lists.List'Class;
+      Visitor : in out Block_Visitor'Class) is
+   begin
+      Visitor.Enter_List (Block);
+
+      for Item of Block loop
+         Visitor.Enter_List_Item (Item);
+
+         Self.Visit_Block_Container (Item, Visitor);
+
+         Visitor.Leave_List_Item (Item);
+      end loop;
+
+      Visitor.Leave_List (Block);
+   end Visit_List;
+
+end Markdown.Blocks.Visitors;

source/backend/markdown-blocks-visitors.ads

@@ -0,0 +1,59 @@
+--
+--  Copyright (C) 2025, AdaCore
+--
+--  SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+--
+
+with Markdown.Documents;
+with Markdown.List_Items;
+
+package Markdown.Blocks.Visitors
+  with Preelaborate
+is
+
+   type Block_Visitor is limited interface;
+
+   not overriding procedure Enter_Indented_Code_Block
+     (Self  : in out Block_Visitor;
+      Block : Markdown.Blocks.Indented_Code.Indented_Code_Block'Class) is null;
+
+   not overriding procedure Leave_Indented_Code_Block
+     (Self  : in out Block_Visitor;
+      Block : Markdown.Blocks.Indented_Code.Indented_Code_Block'Class) is null;
+
+   not overriding procedure Enter_List
+     (Self  : in out Block_Visitor;
+      Block : Markdown.Blocks.Lists.List'Class) is null;
+
+   not overriding procedure Leave_List
+     (Self  : in out Block_Visitor;
+      Block : Markdown.Blocks.Lists.List'Class) is null;
+
+   not overriding procedure Enter_List_Item
+     (Self      : in out Block_Visitor;
+      Container : Markdown.List_Items.List_Item'Class) is null;
+
+   not overriding procedure Leave_List_Item
+     (Self      : in out Block_Visitor;
+      Container : Markdown.List_Items.List_Item'Class'Class) is null;
+
+   not overriding procedure Enter_Paragraph
+     (Self  : in out Block_Visitor;
+      Block : Markdown.Blocks.Paragraphs.Paragraph'Class) is null;
+
+   not overriding procedure Leave_Paragraph
+     (Self  : in out Block_Visitor;
+      Block : Markdown.Blocks.Paragraphs.Paragraph'Class) is null;
+
+   type Block_Iterator is tagged limited private;
+
+   procedure Iterate
+     (Self     : in out Block_Iterator'Class;
+      Document : Markdown.Documents.Document'Class;
+      Visitor  : in out Block_Visitor'Class);
+
+private
+
+   type Block_Iterator is tagged limited null record;
+
+end Markdown.Blocks.Visitors;

source/backend/odf/gnatdoc-backend-odf.adb

@@ -20,7 +20,9 @@ with VSS.XML.XmlAda_Readers;
 with VSS.XML.Templates.Processors;
 with VSS.XML.Writers.Simple;
 
+with GNATdoc.Backend.ODF_Markup.Image_Utilities;
 with GNATdoc.Entities.Proxies;
+with GNATdoc.Projects;
 with Streams;
 
 package body GNATdoc.Backend.ODF is
@@ -118,6 +120,24 @@ package body GNATdoc.Backend.ODF is
       Output.Close;
    end Generate;
 
+   ----------------
+   -- Initialize --
+   ----------------
+
+   overriding procedure Initialize (Self : in out ODF_Backend) is
+   begin
+      Abstract_Backend (Self).Initialize;
+
+      if Self.Image_Directories.Is_Empty then
+         GNATdoc.Backend.ODF_Markup.Image_Utilities.Set_Image_Directories
+           ([GNATdoc.Projects.Project_File_Directory]);
+
+      else
+         GNATdoc.Backend.ODF_Markup.Image_Utilities.Set_Image_Directories
+           (Self.Image_Directories);
+      end if;
+   end Initialize;
+
    ----------------------------------
    -- Process_Command_Line_Options --
    ----------------------------------

source/backend/odf/gnatdoc-backend-odf.ads

@@ -25,7 +25,7 @@ private
       null;
    end record;
 
-   --  overriding procedure Initialize (Self : in out RST_Backend_Base);
+   overriding procedure Initialize (Self : in out ODF_Backend);
 
    overriding procedure Generate (Self : in out ODF_Backend);
 

source/backend/odf/gnatdoc-backend-odf_markup-image_utilities.adb

@@ -20,9 +20,13 @@ with GNAT.Strings;
 
 with VSS.Strings.Conversions;
 with VSS.Strings.Converters.Decoders;
+with VSS.Strings.Formatters.Strings;
+with VSS.Strings.Templates;
 
 with GNATCOLL.Coders.Base64;
 
+with GNATdoc.Messages;
+
 package body GNATdoc.Backend.ODF_Markup.Image_Utilities is
 
    type Stream_Element_Array_Access is
@@ -32,6 +36,12 @@ package body GNATdoc.Backend.ODF_Markup.Image_Utilities is
      new Ada.Unchecked_Deallocation
            (Ada.Streams.Stream_Element_Array, Stream_Element_Array_Access);
 
+   Image_Directories : GNATdoc.Virtual_File_Vectors.Vector;
+
+   Not_Found_Template : constant
+     VSS.Strings.Templates.Virtual_String_Template :=
+       "image file '{}' is not found";
+
    -----------------
    -- Load_Encode --
    -----------------
@@ -42,18 +52,30 @@ package body GNATdoc.Backend.ODF_Markup.Image_Utilities is
    is
       use type Ada.Streams.Stream_Element_Offset;
 
+      Name    : constant GNATCOLL.VFS.Filesystem_String :=
+        GNATCOLL.VFS.Filesystem_String
+          (VSS.Strings.Conversions.To_UTF_8_String (Destination));
       File    : GNATCOLL.VFS.Virtual_File;
       Binary  : GNAT.Strings.String_Access;
       Encoded : Stream_Element_Array_Access;
       Coder   : GNATCOLL.Coders.Base64.Encoder_Type;
 
    begin
-      File :=
-        GNATCOLL.VFS.Create_From_UTF8
-          (VSS.Strings.Conversions.To_UTF_8_String (Destination));
+      for Directory of Image_Directories loop
+         File :=
+           GNATCOLL.VFS.Create_From_Base
+             (Base_Name => Name,
+              Base_Dir  => Directory.Full_Name.all);
+
+         exit when File.Is_Regular_File;
+      end loop;
 
       if not File.Is_Regular_File then
-         raise Program_Error;
+         GNATdoc.Messages.Report_Warning
+           (Not_Found_Template.Format
+              (VSS.Strings.Formatters.Strings.Image (Destination)));
+
+         return;
       end if;
 
       Binary := File.Read_File;
@@ -86,4 +108,14 @@ package body GNATdoc.Backend.ODF_Markup.Image_Utilities is
       GNAT.Strings.Free (Binary);
    end Load_Encode;
 
+   ---------------------------
+   -- Set_Image_Directories --
+   ---------------------------
+
+   procedure Set_Image_Directories
+     (To : GNATdoc.Virtual_File_Vectors.Vector) is
+   begin
+      Image_Directories := To;
+   end Set_Image_Directories;
+
 end GNATdoc.Backend.ODF_Markup.Image_Utilities;

source/backend/odf/gnatdoc-backend-odf_markup-image_utilities.ads

@@ -23,4 +23,7 @@ package GNATdoc.Backend.ODF_Markup.Image_Utilities is
    --  Loads given file, converts its content into Base64 encoded form and
    --  transforms to `Virtual_String`.
 
+   procedure Set_Image_Directories (To : GNATdoc.Virtual_File_Vectors.Vector);
+   --  Set list of directories to lookup for image files.
+
 end GNATdoc.Backend.ODF_Markup.Image_Utilities;

source/backend/rst/gnatdoc-backend-rst.adb

@@ -36,11 +36,6 @@ package body GNATdoc.Backend.RST is
       Entity : Entity_Information);
    --  Generate RTS file for given entity.
 
-   function "*"
-     (Count : VSS.Strings.Character_Count;
-      Item  : VSS.Characters.Virtual_Character)
-      return VSS.Strings.Virtual_String;
-
    OOP_Style_Option : constant VSS.Command_Line.Binary_Option :=
      (Short_Name  => <>,
       Long_Name   => "rst-oop-style",
@@ -49,22 +44,6 @@ package body GNATdoc.Backend.RST is
           ("Group subprograms by tagged types, generating a page for each"
            & " tagged type"));
 
-   ---------
-   -- "*" --
-   ---------
-
-   function "*"
-     (Count : VSS.Strings.Character_Count;
-      Item  : VSS.Characters.Virtual_Character)
-      return VSS.Strings.Virtual_String is
-   begin
-      return Result : VSS.Strings.Virtual_String do
-         for J in 1 .. Count loop
-            Result.Append (Item);
-         end loop;
-      end return;
-   end "*";
-
    ------------------------------
    -- Add_Command_Line_Options --
    ------------------------------
@@ -133,6 +112,8 @@ package body GNATdoc.Backend.RST is
      (Self   : in out RST_Backend_Base'Class;
       Entity : Entity_Information)
    is
+      use type VSS.Strings.Character_Count;
+
       Name    : constant GNATCOLL.VFS.Virtual_File :=
         GNATCOLL.VFS.Create_From_Base
           (GNATCOLL.VFS.Filesystem_String
@@ -240,11 +221,11 @@ package body GNATdoc.Backend.RST is
    begin
       File.Open (Name);
 
-      File.Put (Entity.Qualified_Name.Character_Length * '*', Success);
       File.New_Line (Success);
       File.Put (Entity.Qualified_Name, Success);
       File.New_Line (Success);
-      File.Put (Entity.Qualified_Name.Character_Length * '*', Success);
+      File.Put ((Entity.Qualified_Name.Character_Length + 2) * '*', Success);
+      File.New_Line (Success);
       File.New_Line (Success);
 
       File.Put (".. ada:set_package:: ", Success);
@@ -355,7 +336,6 @@ package body GNATdoc.Backend.RST is
                Right : not null GNATdoc.Entities.Entity_Information_Access)
                return Boolean
             is
-               use type VSS.Strings.Character_Count;
                use type VSS.Strings.Line_Count;
                use type VSS.Strings.Virtual_String;