feat: tagfiles generation for cross-referencing in doxygen format

Author: fpelliccioni

docs/mrdocs.schema.json

@@ -244,6 +244,12 @@
       "title": "System include paths",
       "type": "array"
     },
+    "tagfile-path": {
+      "default": "<output>/reference.tag.xml",
+      "description": "Specifies the full path (filename) where the generated tagfile should be saved. If left empty, no tagfile will be generated.",
+      "title": "Path for the tagfile",
+      "type": "string"
+    },
     "use-system-stdlib": {
       "default": false,
       "description": "True if the compiler has to use just the system standard library. When set to true, the compiler uses the system standard library instead of the standard library provided by the compiler.",

include/mrdocs/Corpus.hpp

@@ -159,6 +159,39 @@ class MRDOCS_VISIBLE
         }
     }
 
+    /** Visit the members of specified Info.
+     
+        This function iterates the members of the specified
+        Info `I`. For each member associated with a
+        function with the same name as the member, the
+        function object `f` is invoked with the member
+        as the first argument, followed by `args...`.
+
+        When there are more than one member function
+        with the same name, the function object `f` is
+        invoked with an @ref OverloadSet as the first
+        argument, followed by `args...`.    
+        
+        @param I The Info to traverse.
+        @param pred The predicate to use to determine if the member should be visited.
+        @param f The function to invoke with the member as the first argument, followed by `args...`.
+        @param args The arguments to pass to the function.
+    */
+    template <InfoParent T, class Pred, class F, class... Args>
+    void
+    traverseIf(
+        T const& I, Pred&& pred, F&& f, Args&&... args) const
+    {
+        for (auto const& id : I.Members)
+        {
+            if (std::forward<Pred>(pred)(get(id)))
+            {
+                visit(get(id), std::forward<F>(f),
+                      std::forward<Args>(args)...);
+            }
+        }
+    }    
+
     /** Visit the member overloads of specified ScopeInfo.
 
         This function iterates the members of the

include/mrdocs/Generator.hpp

@@ -182,6 +182,29 @@ class MRDOCS_VISIBLE
         Corpus const& corpus) const;
 };
 
+/** Return the full path for single page output.
+
+    This function determines the full path for a single-page output file
+    based on the provided `outputPath` and file `extension`.
+
+    If the `outputPath` already exists:
+    - If it is a directory, appends the default file name with the provided extension.
+    - If it is a file, uses the provided `outputPath` directly.
+
+    If the `outputPath` does not exist:
+    - If it ends with a '/', assumes it is a directory and appends the default file name.
+    - Otherwise, it returns an error because the path is ambiguous.
+
+    @return The full path or an error if the `outputPath` is ambiguous.
+
+    @param outputPath The specified output path, which can be a directory or file.
+    @param extension The file extension to use for single-page output.
+*/
+Expected<std::string>
+getSinglePageFullPath(
+    std::string_view outputPath,
+    std::string_view extension);
+
 } // mrdocs
 } // clang
 

src/lib/Gen/hbs/HandlebarsGenerator.cpp

@@ -15,7 +15,17 @@
 #include "Builder.hpp"
 #include "MultiPageVisitor.hpp"
 #include "SinglePageVisitor.hpp"
+
+#include "lib/Lib/TagfileWriter.hpp"
+#include "lib/Support/RawOstream.hpp"
+
+#include <llvm/ADT/SmallString.h>
+#include <llvm/Support/FileSystem.h>
+#include <llvm/Support/Path.h>
+
 #include <mrdocs/Support/Path.hpp>
+
+#include <fstream>
 #include <sstream>
 
 namespace clang {
@@ -30,6 +40,30 @@ createEscapeFn(HandlebarsGenerator const& gen)
     };
 }
 
+namespace {
+
+/** Generate a Tagfile to enable cross-referencing between documentation symbols. */
+Expected<void>
+generateTagfile(
+    HandlebarsCorpus const& hbsCorpus,
+    std::string_view tagFilePath,
+    std::string_view outputFilesBasePath
+    )
+{
+    MRDOCS_ASSERT(!tagFilePath.empty());
+
+    auto tagFileWriterEx = TagfileWriter::create(hbsCorpus, tagFilePath, outputFilesBasePath);
+    MRDOCS_CHECK_OR(tagFileWriterEx, Unexpected(tagFileWriterEx.error()));
+
+    auto tagfileWriter = std::move(*tagFileWriterEx);
+    tagfileWriter.initialize();
+    visit(hbsCorpus->globalNamespace(), tagfileWriter);
+    tagfileWriter.finalize();
+    return {};
+}
+
+} // anonymous namespace
+
 Expected<ExecutorGroup<Builder>>
 createExecutors(
     HandlebarsGenerator const& gen,
@@ -79,7 +113,17 @@ build(
 {
     if (!corpus.config->multipage)
     {
-        return Generator::build(outputPath, corpus);
+        auto e = Generator::build(outputPath, corpus);
+        if (e.has_value() && !corpus.config->tagfilePath.empty())
+        {
+            // Generate tagfile if specified
+            auto const singlePageFileName = getSinglePageFullPath(outputPath, fileExtension());
+            MRDOCS_CHECK_OR(singlePageFileName, Unexpected(singlePageFileName.error()));
+            HandlebarsCorpus hbsCorpus = createDomCorpus(*this, corpus);
+            return generateTagfile(hbsCorpus, corpus.config->tagfilePath, *singlePageFileName);
+        }
+
+        return e;
     }
 
     // Create corpus and executors
@@ -93,6 +137,12 @@ build(
     // Wait for all executors to finish and check errors
     auto errors = ex.wait();
     MRDOCS_CHECK_OR(errors.empty(), Unexpected(errors));
+
+    if (! corpus.config->tagfilePath.empty())
+    {
+        return generateTagfile(domCorpus, corpus.config->tagfilePath, outputPath);
+    }
+
     return {};
 }
 

src/lib/Gen/xml/XMLTags.cpp

@@ -193,6 +193,9 @@ void
 XMLTags::
 nest(int levels)
 {
+    if (!nesting_)
+        return;
+    
     if(levels > 0)
     {
         indent_.append(levels * 2, ' ');

src/lib/Gen/xml/XMLTags.hpp

@@ -186,6 +186,7 @@ class XMLTags
 public:
     std::string indent_;
     llvm::raw_ostream& os_;
+    bool nesting_ = true;
 
     explicit
     XMLTags(
@@ -201,6 +202,7 @@ class XMLTags
     void write(dom::String const&,
         llvm::StringRef value = {}, Attributes = {});
     void close(dom::String const&);
+    void nesting(bool enable) noexcept { nesting_ = enable; }
 
     void nest(int levels);
 };

src/lib/Lib/ConfigOptions.json

@@ -148,6 +148,15 @@
         "default": "<mrdocs-root>/share/mrdocs/addons",
         "relativeto": "<config-dir>"
       },
+      {
+        "name": "tagfile-path",
+        "brief": "Path for the tagfile",
+        "details": "Specifies the full path (filename) where the generated tagfile should be saved. If left empty, no tagfile will be generated.",
+        "type": "file-path",
+        "default": "<output>/reference.tag.xml",
+        "relativeto": "<output>",
+        "must-exist": false
+      },
       {
         "name": "legible-names",
         "brief": "Use legible names",