feat: tagfiles generation for cross-referencing in doxygen format

Author: fpelliccioni

.github/workflows/ci.yml

@@ -644,8 +644,9 @@ jobs:
             for generator in "${generators[@]}"; do
               [[ $generator = xml && $variant = multi ]] && continue
               [[ $variant = multi ]] && multipage="true" || multipage="false"
+              echo "Generating demos for $variant/$generator"
               mrdocs --config="$(pwd)/boost/libs/url/doc/mrdocs.yml" "../CMakeLists.txt" --output="$(pwd)/demos/boost-url/$variant/$generator" --multipage=$multipage --generate="$generator"
-              echo "Number of files in demos/boost-url/$variant/$format: $(find demos/boost-url/$variant/$format -type f | wc -l)"
+              echo "Number of files in demos/boost-url/$variant/$generator: $(find demos/boost-url/$variant/$generator -type f | wc -l)"
             done
           done
           

docs/mrdocs.schema.json

@@ -244,6 +244,12 @@
       "title": "System include paths",
       "type": "array"
     },
+    "tagfile-path": {
+      "default": "",
+      "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

src/lib/Gen/hbs/HandlebarsGenerator.cpp

@@ -15,13 +15,73 @@
 #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 {
 namespace mrdocs {
 namespace hbs {
 
+namespace {
+
+/** Generate a Tagfile for cross-referencing. */
+Error
+generateTagfile(
+    HandlebarsCorpus const& hbsCorpus,
+    std::string_view tagFilePath,
+    std::string_view generatedFilesPath,
+    bool isSinglePage)
+{
+    if (tagFilePath.empty())
+        return Error::success();
+
+    auto tagFileWriterEx = TagfileWriter::create(hbsCorpus, tagFilePath, generatedFilesPath, isSinglePage);
+    if (!tagFileWriterEx)
+        return tagFileWriterEx.error();
+
+    auto tagfileWriter = std::move(*tagFileWriterEx);
+    tagfileWriter.initialize();
+    visit(hbsCorpus->globalNamespace(), tagfileWriter);
+    tagfileWriter.finalize();
+    return Error::success();
+}
+
+std::string 
+getSinglePageFileName(
+    std::string_view outputPath, 
+    std::string_view extension)
+{
+    namespace path = llvm::sys::path;
+
+    using SmallString = llvm::SmallString<0>;
+
+    SmallString ext(".");
+    ext += extension;
+
+    SmallString fileName(outputPath);
+    if(path::extension(outputPath).compare_insensitive(ext) != 0)
+    {
+        // directory specified
+        path::append(fileName, "reference");
+        path::replace_extension(fileName, ext);
+    }
+
+    return fileName.str().str();
+}
+
+
+} // anonymous namespace    
+
 Expected<ExecutorGroup<Builder>>
 createExecutors(
     HandlebarsCorpus const& hbsCorpus)
@@ -70,7 +130,16 @@ build(
 {
     if (!corpus.config->multipage)
     {
-        return Generator::build(outputPath, corpus);
+        Error e = Generator::build(outputPath, corpus);
+        if (!e.failed() && !corpus.config->tagfilePath.empty())
+        {
+            // Generate tagfile if specified
+            auto const singlePageFileName = getSinglePageFileName(outputPath, fileExtension());
+            HandlebarsCorpus hbsCorpus = createDomCorpus(*this, corpus);
+            return generateTagfile(hbsCorpus, corpus.config->tagfilePath, singlePageFileName, true);
+        }
+
+        return e;
     }
 
     // Create corpus and executors
@@ -84,7 +153,15 @@ build(
 
     // Wait for all executors to finish and check errors
     auto errors = ex->wait();
-    MRDOCS_CHECK_OR(errors.empty(), errors);
+    if (!errors.empty())
+    {
+        return Error(errors);
+    }
+    if (!corpus.config->tagfilePath.empty())
+    {
+        return generateTagfile(domCorpus, corpus.config->tagfilePath, outputPath, false);
+    }
+
     return Error::success();
 }
 

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",
+        "must-exist": false,
+        "default": "",
+        "relativeto": "<config-dir>"
+      },      
       {
         "name": "legible-names",
         "brief": "Use legible names",