Add PDF generation ability to Microsoft.DocAsCode.App

src/Docfx.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/Docfx.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/Docfx.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) the templates subfolder exists inside your application folder or your docfx.json directory.");
+        }
         Tokens = TemplateProcessorUtility.LoadTokens(resourceProvider) ?? new Dictionary<string, string>();
     }
 

test/Docfx.Build.RestApi.Tests/RestApiDocumentProcessorTest.cs

@@ -294,7 +294,7 @@ public void ProcessSwaggerWithInvalidLinksOverwriteShouldSucceedWithWarning()
             files.Add(DocumentType.Overwrite, new[] { "TestData/overwrite/rest.overwrite.invalid.links.second.md" });
             BuildDocument(files);
 
-            Assert.Equal(6, listener.Items.Count); // Additional warning for "There is no template processing document type(s): RestApi"
+            Assert.Equal(7, listener.Items.Count); // Additional warning for "There is no template processing document type(s): RestApi"
 
             var outputRawModelPath = GetRawModelFilePath("contacts.json");
             Assert.True(File.Exists(outputRawModelPath));

test/Docfx.Build.SchemaDriven.Tests/SchemaDrivenProcessorTest.cs

@@ -321,7 +321,7 @@ public void TestValidMetadataReferenceWithIncremental()
             BuildDocument(files);
         }
 
-        Assert.Equal(3, listener.Items.Count);
+        Assert.Equal(4, listener.Items.Count);
         Assert.NotNull(listener.Items.FirstOrDefault(s => s.Message.StartsWith("There is no template processing document type(s): MetadataReferenceTest,Toc")));
         listener.Items.Clear();
 
@@ -433,7 +433,7 @@ public void TestUidWithPatternedTag()
             },
         });
 
-        Assert.Equal(2, listener.Items.Count);
+        Assert.Equal(3, listener.Items.Count);
         Assert.NotNull(listener.Items.FirstOrDefault(s => s.Message.StartsWith("There is no template processing document type(s): PatternedUid")));
         listener.Items.Clear();
 

test/Docfx.Build.SchemaDriven.Tests/SchemaMergerTest.cs

@@ -222,7 +222,7 @@ Overwrite with content
         BuildDocument(files);
 
         // One plugin warning for yml and one plugin warning for overwrite file
-        Assert.Equal(6, listener.Items.Count);
+        Assert.Equal(7, listener.Items.Count);
         Assert.NotNull(listener.Items.FirstOrDefault(s => s.Message.StartsWith("There is no template processing document type(s): testmerger")));
         Assert.Equal(1, listener.Items.Count(s => s.Message.StartsWith("\"/stringArrayValue/0\" in overwrite object fails to overwrite \"/stringArrayValue\" for \"uid1\" because it does not match any existing item.")));
         Assert.Equal(1, listener.Items.Count(s => s.Message.StartsWith("\"/intArrayValue/0\" in overwrite object fails to overwrite \"/intArrayValue\" for \"uid1\" because it does not match any existing item.")));

test/Docfx.Build.UniversalReference.Tests/UniversalReferenceDocumentProcessorTest.cs

@@ -176,8 +176,8 @@ public void ProcessItemWithEmptyUidShouldFail()
         using var listener = new TestListenerScope(nameof(UniversalReferenceDocumentProcessorTest));
         BuildDocument(files);
         Assert.NotNull(listener.Items);
-        Assert.Single(listener.Items);
-        Assert.Contains("Uid must not be null or empty", listener.Items[0].Message);
+        Assert.Equal(2, listener.Items.Count);
+        Assert.Contains("Uid must not be null or empty", listener.Items[1].Message);
     }
 
     private void BuildDocument(FileCollection files)

test/docfx.Tests/Attributes/WindowsOnlyFactAttribute.cs

@@ -0,0 +1,25 @@
+// Copyright (c) .NET Foundation and contributors. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+using System.Runtime.InteropServices;
+using Xunit;
+
+namespace docfx.Tests.Attributes
+{
+    /// <summary>
+    /// XUnit Fact attribute that skips the test if the OS is not Windows.
+    /// </summary>
+    /// <remarks>
+    /// Taken from https://github.com/dotnet/sdk/blob/a30e465a2e2ea4e2550f319a2dc088daaafe5649/src/Tests/Microsoft.NET.TestFramework/Attributes/WindowsOnlyFactAttribute.cs
+    /// </remarks>
+    public class WindowsOnlyFactAttribute : FactAttribute
+    {
+        public WindowsOnlyFactAttribute()
+        {
+            if (!RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
+            {
+                this.Skip = "This test requires Windows to run";
+            }
+        }
+    }
+}

test/docfx.Tests/DocsetTest.cs → test/docfx.Tests/DocsetBuildTest.cs

@@ -11,11 +11,11 @@
 namespace Docfx.Tests;
 
 [Collection("docfx STA")]
-public class DocsetTest : TestBase
+public class DocsetBuildTest : TestBase
 {
     private static async Task<Dictionary<string, Func<string>>> Build(Dictionary<string, string> files, [CallerMemberName] string testName = null)
     {
-        var testDirectory = $"{nameof(DocsetTest)}/{testName}";
+        var testDirectory = $"{nameof(DocsetBuildTest)}/{testName}";
         var outputDirectory = $"{testDirectory}/_site";
 
         if (Directory.Exists(testDirectory))
@@ -35,6 +35,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(DocsetBuildTest)}/{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()
     {