feat: tagfiles

fix #650

Author: fpelliccioni

docs/mrdocs.schema.json

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

@@ -143,6 +143,7 @@ class MRDOCS_VISIBLE
         The type of the first argument is determined
         by the `InfoKind` of the `Info` object.
 
+        @param I The Info to visit.
         @param info The Info to visit.
         @param f The function to invoke.
         @param args The arguments to pass to the function.
@@ -202,6 +203,14 @@ class MRDOCS_VISIBLE
     getFullyQualifiedName(
         const Info& I,
         std::string& temp) const;
+
+    std::string
+    getFullyQualifiedName(const Info& I) const
+    {
+        std::string temp;
+        return getFullyQualifiedName(I, temp);
+    }
+
 };
 
 //------------------------------------------------

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 {
@@ -79,7 +89,21 @@ build(
 {
     if (!corpus.config->multipage)
     {
-        return Generator::build(outputPath, corpus);
+        auto e = Generator::build(outputPath, corpus);
+        if (e.has_value() && !corpus.config->tagfile.empty())
+        {
+            // Generate tagfile if specified
+            auto const singlePagePath = getSinglePageFullPath(outputPath, fileExtension());
+            MRDOCS_CHECK_OR(singlePagePath, Unexpected(singlePagePath.error()));
+            HandlebarsCorpus hbsCorpus = createDomCorpus(*this, corpus);
+            MRDOCS_TRY(auto tagFileWriter, TagfileWriter::create(
+                    hbsCorpus,
+                    corpus.config->tagfile,
+                    files::getFileName(*singlePagePath)));
+            tagFileWriter.build();
+        }
+
+        return e;
     }
 
     // Create corpus and executors
@@ -93,6 +117,16 @@ build(
     // Wait for all executors to finish and check errors
     auto errors = ex.wait();
     MRDOCS_CHECK_OR(errors.empty(), Unexpected(errors));
+
+    if (! corpus.config->tagfile.empty())
+    {
+        MRDOCS_TRY(auto tagFileWriter, TagfileWriter::create(
+                domCorpus,
+                corpus.config->tagfile,
+                outputPath));
+        tagFileWriter.build();
+    }
+
     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",
+        "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",