Add PDF generation ability to Microsoft.DocAsCode.App

src/Microsoft.DocAsCode.App/Docset.cs

@@ -29,6 +29,44 @@ public static Task Build(string configPath)
     /// <param name="options">The build options.</param>
     /// <returns>A task to await for build completion.</returns>
     public static Task Build(string configPath, BuildOptions options)
+    {
+        return Exec<BuildJsonConfig>(
+            configPath,
+            options,
+            "build",
+            (config, exeOptions, configDirectory, outputDirectory) => RunBuild.Exec(config, exeOptions, configDirectory, outputDirectory));
+    }
+
+    /// <summary>
+    /// Builds a pdf specified by docfx.json config.
+    /// </summary>
+    /// <param name="configPath">The path to docfx.json config file.</param>
+    /// <returns>A task to await for build completion.</returns>
+    public static Task Pdf(string configPath)
+    {
+        return Pdf(configPath, new());
+    }
+
+    /// <summary>
+    /// Builds a pdf specified by docfx.json config.
+    /// </summary>
+    /// <param name="configPath">The path to docfx.json config file.</param>
+    /// <param name="options">The build options.</param>
+    /// <returns>A task to await for build completion.</returns>
+    public static Task Pdf(string configPath, BuildOptions options)
+    {
+        return Exec<PdfJsonConfig>(
+            configPath,
+            options,
+            "pdf",
+            (config, exeOptions, configDirectory, outputDirectory) => RunPdf.Exec(config, exeOptions, configDirectory, outputDirectory));
+    }
+
+    private static Task Exec<TConfig>(
+        string configPath,
+        BuildOptions options,
+        string elementKey,
+        Action<TConfig, BuildOptions, string, string> execAction)
     {
         var consoleLogListener = new ConsoleLogListener();
         Logger.RegisterListener(consoleLogListener);
@@ -37,9 +75,19 @@ public static Task Build(string configPath, BuildOptions options)
         {
             var configDirectory = Path.GetDirectoryName(Path.GetFullPath(configPath));
 
+            var defaultSerializer = JsonUtility.DefaultSerializer.Value;
+
             var config = JObject.Parse(File.ReadAllText(configPath));
-            if (config.TryGetValue("build", out var value))
-                RunBuild.Exec(value.ToObject<BuildJsonConfig>(JsonUtility.DefaultSerializer.Value), options, configDirectory);
+
+            if (config.TryGetValue(elementKey, out var value))
+            {
+                execAction(value.ToObject<TConfig>(defaultSerializer), options, configDirectory, null);
+            }
+            else
+            {
+                Logger.LogError($"Unable to find '{elementKey}' in '{configPath}'.");
+            }
+
             return Task.CompletedTask;
         }
         finally

src/Microsoft.DocAsCode.Build.Engine/TemplateProcessors/TemplateModelTransformer.cs

@@ -77,6 +77,7 @@ internal ManifestItem Transform(InternalManifestItem item)
         var templateBundle = _templateCollection[item.DocumentType];
         if (templateBundle == null)
         {
+            Logger.LogInfo($"No template bundle found for {item.DocumentType}, model will be ignored.");
             return manifestItem;
         }
 

src/Microsoft.DocAsCode.Build.Engine/TemplateProcessors/TemplateProcessor.cs

@@ -35,6 +35,10 @@ public TemplateProcessor(ResourceFileReader resourceProvider, DocumentBuildConte
         _resourceProvider = resourceProvider;
         _maxParallelism = maxParallelism;
         _templateCollection = new TemplateCollection(resourceProvider, context, maxParallelism);
+        if (_templateCollection.Count == 0)
+        {
+            Logger.LogWarning("No template bundles were found, no template will be applied to the documents. 1) Check your docfx.json 2) or your working directory has the templates subfolder");
+        }
         Tokens = TemplateProcessorUtility.LoadTokens(resourceProvider) ?? new Dictionary<string, string>();
     }
 

test/docfx.Tests/DocsetTest.cs

@@ -7,6 +7,8 @@
 using Microsoft.DocAsCode.Tests.Common;
 
 using Xunit;
+using Xunit.Abstractions;
+using Xunit.Sdk;
 
 namespace Microsoft.DocAsCode.Tests;
 
@@ -35,6 +37,31 @@ private static async Task<Dictionary<string, Func<string>>> Build(Dictionary<str
                             f => new Func<string>(() => File.ReadAllText(f)));
     }
 
+    private static async Task<Dictionary<string, Func<string>>> Pdf(Dictionary<string, string> files, [CallerMemberName] string testName = null)
+    {
+        var testDirectory = $"{nameof(DocsetTest)}/{testName}";
+        var outputDirectory = $"{testDirectory}/_pdf";
+
+        if (Directory.Exists(testDirectory))
+            Directory.Delete(testDirectory, recursive: true);
+
+        Directory.CreateDirectory(testDirectory);
+        foreach (var (path, content) in files)
+        {
+            var targetPath = Path.Combine(testDirectory, path);
+            Directory.CreateDirectory(Path.GetDirectoryName(targetPath));
+
+            File.WriteAllText(targetPath, content);
+        }
+
+        await Docset.Pdf($"{testDirectory}/docfx.json");
+
+        return Directory.GetFiles(outputDirectory, "*", SearchOption.AllDirectories)
+            .ToDictionary(
+                f => Path.GetRelativePath(outputDirectory, f),
+                f => new Func<string>(() => File.ReadAllText(f)));
+    }
+
     [Fact]
     public static async Task CustomLogo_Override_LogoFromTemplate()
     {
@@ -168,7 +195,6 @@ public static async Task Build_With_File_Metadata_Files()
         Assert.Equal("fileMetadata2.json", b.GetProperty("meta1").GetString());
     }
 
-    [Fact]
     public static async Task Build_With_RedirectUri_Files()
     {
         // Act
@@ -217,4 +243,164 @@ public static async Task Build_With_RedirectUri_Files()
         var urls = XDocument.Parse(sitemapXml).Root.Elements();
         Assert.True(urls.Count() == 0);
     }
+
+    [Fact]
+    public static async Task Pdf_Basic()
+    {
+        var outputs = await Pdf(new()
+        {
+            ["docfx.json"] =
+                """
+                {
+                "pdf": {
+                    "content": [
+                        {
+                            "files": [
+                                "**/**.md"
+                            ]
+                        },
+                        {
+                            "files": "**/toc.yml"
+                        }
+                    ],
+                    "wkhtmltopdf": {
+                        "additionalArguments": "--enable-local-file-access"
+                    },
+                    "dest": "_pdf"
+                }
+                }
+                """,
+            ["pdf/toc.yml"] = "- name: Introduction\r\n  href: intro.md\r\n- name: Another Page\r\n  href: anotherpage.md\r\n",
+            ["pdf/intro.md"] = "# Introduction\r\n\r\n",
+            ["pdf/anotherpage.md"] = "# Another Page\r\n\r\n"
+        });
+
+        Assert.True(outputs.ContainsKey("Pdf_Basic_pdf.pdf"));
+    }
+
+    [Fact]
+    public static async Task Pdf_With_Cover_Page()
+    {
+        var outputs = await Pdf(new()
+        {
+            ["docfx.json"] =
+                """
+                {
+                "pdf": {
+                    "content": [
+                        {
+                            "files": [
+                                "**/**.md"
+                            ]
+                        },
+                        {
+                            "files": "**/toc.yml"
+                        }
+                    ],
+                    "wkhtmltopdf": {
+                        "additionalArguments": "--enable-local-file-access"
+                    },
+                    "dest": "_pdf"
+                }
+                }
+                """,
+            ["pdf/toc.yml"] = "- name: Introduction\r\n  href: intro.md\r\n- name: Another Page\r\n  href: anotherpage.md\r\n",
+            ["pdf/cover.md"] = "# My Basic Cover Page\r\n\r\n",
+            ["pdf/intro.md"] = "# Introduction\r\n\r\n",
+            ["pdf/anotherpage.md"] = "# Another Page\r\n\r\n"
+        });
+
+        Assert.True(outputs.ContainsKey("Pdf_With_Cover_Page_pdf.pdf"));
+    }
+
+    [Fact]
+    public static async Task Pdf_With_Global_Metadata_Files()
+    {
+        var outputs = await Pdf(new()
+        {
+            ["docfx.json"] =
+                """
+                {
+                    "pdf": {
+                        "content": [{ "files": [ "*.md" ] },{ "files": "toc.yml" }],
+                        "dest": "_pdf",
+                        "exportRawModel": true,
+                        "globalMetadataFiles": ["projectMetadata1.json", "projectMetadata2.json"],
+                        "globalMetadata": {
+                            "meta1": "docfx.json",
+                            "meta3": "docfx.json"
+                        }
+                    }
+                }
+                """,
+            ["projectMetadata1.json"] =
+                """
+                {
+                    "meta1": "projectMetadata1.json",
+                    "meta2": "projectMetadata2.json"
+                }
+                """,
+            ["projectMetadata2.json"] =
+                """
+                {
+                    "meta2": "projectMetadata2.json"
+                }
+                """,
+            ["toc.yml"] = "- name: Introduction\r\n  href: intro.md\r\n- name: Another Page\r\n  href: anotherpage.md\r\n",
+            ["cover.md"] = "# My Basic Cover Page\r\n\r\n",
+            ["intro.md"] = "# Introduction\r\n\r\n",
+            ["anotherpage.md"] = "# Another Page\r\n\r\n"
+        });
+
+        Assert.True(outputs.ContainsKey("Pdf_With_Global_Metadata_Files.pdf"));
+    }
+
+    [Fact]
+    public static async Task Pdf_With_File_Metadata_Files()
+    {
+        var outputs = await Pdf(new()
+        {
+            ["docfx.json"] =
+                """
+                {
+                    "pdf": {
+                        "content": [{ "files": [ "*.md" ] },{ "files": "toc.yml" }],
+                        "dest": "_pdf",
+                        "exportRawModel": true,
+                        "fileMetadataFiles": ["fileMetadata1.json", "fileMetadata2.json"],
+                        "fileMetadata": {
+                            "meta1": {
+                              "a.md": "docfx.json"
+                            }
+                        }
+                    }
+                }
+                """,
+            ["fileMetadata1.json"] =
+                """
+                {
+                    "meta1": {
+                        "a.md": "fileMetadata1.json",
+                        "b.md": "fileMetadata1.json"
+                    }
+                }
+                """,
+            ["fileMetadata2.json"] =
+                """
+                {
+                    "meta1": {
+                        "b.md": "fileMetadata2.json"
+                    }
+                }
+                """,
+            ["a.md"] = "",
+            ["b.md"] = "",
+            ["toc.yml"] = "- name: Introduction\r\n  href: intro.md\r\n- name: Another Page\r\n  href: anotherpage.md\r\n",
+            ["cover.md"] = "# My Basic Cover Page\r\n\r\n",
+            ["intro.md"] = "# Introduction\r\n\r\n",
+            ["anotherpage.md"] = "# Another Page\r\n\r\n"
+        });
+
+        Assert.True(outputs.ContainsKey("Pdf_With_File_Metadata_Files.pdf"));
+    }
 }