(build) improving the docs task - support smart and forced publishing

Author: arturcic

build/Directory.Packages.props

@@ -7,7 +7,6 @@
         <PackageReference Include="Cake.Docker" Version="1.0.0" />
         <PackageReference Include="Cake.Frosting" Version="1.1.0" />
         <PackageReference Include="Cake.Git" Version="1.1.0" />
-        <PackageReference Include="Cake.Kudu" Version="1.0.1" />
         <PackageReference Include="Cake.Json" Version="6.0.1" />
         <PackageReference Include="Cake.Incubator" Version="6.0.0" />
         <PackageReference Include="Cake.Wyam" Version="2.2.12" />

build/common/Utilities/Paths.cs

@@ -4,11 +4,13 @@ namespace Common.Utilities
 {
     public class Paths
     {
-        public static readonly DirectoryPath ToolsDirectory = "./tools";
-        public static readonly DirectoryPath Artifacts = "./artifacts";
-        public static readonly DirectoryPath Src = "./src";
-        public static readonly DirectoryPath Docs = "./docs";
-        public static readonly DirectoryPath Build = "./build";
+        public static readonly DirectoryPath Root = "./";
+
+        public static readonly DirectoryPath ToolsDirectory = $"{Root}tools";
+        public static readonly DirectoryPath Artifacts = $"{Root}artifacts";
+        public static readonly DirectoryPath Src = $"{Root}src";
+        public static readonly DirectoryPath Docs = $"{Root}docs";
+        public static readonly DirectoryPath Build = $"{Root}build";
 
         public static readonly DirectoryPath Nuspec = $"{Build}/nuspec";
 

build/docs/BuildContext.cs

@@ -7,6 +7,7 @@ namespace Docs
 {
     public class BuildContext : BuildContextBase
     {
+        public bool ForcePublish { get; set; }
         public Credentials? Credentials { get; set; }
 
         public WyamSettings? WyamSettings { get; set; }

build/docs/BuildLifetime.cs

@@ -1,4 +1,5 @@
 using System.Collections.Generic;
+using Cake.Common;
 using Cake.Common.IO;
 using Cake.Wyam;
 using Common.Utilities;
@@ -13,6 +14,7 @@ public override void Setup(BuildContext context)
             base.Setup(context);
 
             context.Credentials = Credentials.GetCredentials(context);
+            context.ForcePublish = context.HasArgument("force");
 
             context.WyamSettings = new WyamSettings
             {

build/docs/Tasks/PublishDocs.cs

@@ -1,32 +1,58 @@
 using System;
+using System.Linq;
 using Cake.Common.Diagnostics;
 using Cake.Common.IO;
 using Cake.Core;
 using Cake.Core.IO;
 using Cake.Frosting;
 using Cake.Git;
-using Cake.Kudu;
-using Cake.Kudu.KuduSync;
+using Cake.Wyam;
 using Common.Utilities;
 
 namespace Docs.Tasks
 {
     [TaskName(nameof(PublishDocs))]
     [TaskDescription("Published the docs changes to docs specific branch")]
-    [IsDependentOn(typeof(BuildDocs))]
+    [IsDependentOn(typeof(Clean))]
     public sealed class PublishDocs : FrostingTask<BuildContext>
     {
         public override bool ShouldRun(BuildContext context)
         {
             var shouldRun = true;
             shouldRun &= context.ShouldRun(context.DirectoryExists(Paths.Docs), "Wyam documentation directory is missing");
+            shouldRun &= context.ShouldRun(context.IsStableRelease || context.IsPreRelease, $"{nameof(PublishDocs)} works only for releases.");
 
             return shouldRun;
         }
 
         public override void Run(BuildContext context)
         {
-            PublishDocumentation(context);
+            if (context.ForcePublish is false)
+            {
+                if (AnyDocsChanged(context))
+                {
+                    context.Information("Performing a docs publish. Detected docs changes");
+                    PublishDocumentation(context);
+                }
+                else
+                {
+                    context.Information("No docs have changed, so no need to generate documentation");
+                }
+            }
+            else
+            {
+                context.Information("Performing a forced docs publish...");
+                PublishDocumentation(context);
+            }
+        }
+        private static bool AnyDocsChanged(ICakeContext context)
+        {
+            var sourceCommit = context.GitLogTip(Paths.Root);
+            var filesChanged = context.GitDiff(Paths.Root, sourceCommit.Sha);
+
+            const string path = "docs/";
+            var docFileChanged = filesChanged.Any(file => file.OldPath.StartsWith(path) || file.Path.StartsWith(path) || file.Path.Contains("config.wyam"));
+            return docFileChanged;
         }
 
         private static void PublishDocumentation(BuildContext context)
@@ -42,32 +68,31 @@ private static void PublishDocumentation(BuildContext context)
                 BranchName = publishBranchName
             });
 
-            context.Information("Sync output files...");
-            context.Kudu().Sync(context.MakeAbsolute(Paths.ArtifactsDocs.Combine("preview")), publishFolder, new KuduSyncSettings
+            if (context.WyamSettings is not null)
             {
-                ArgumentCustomization = args => args.Append("--ignore").AppendQuoted(".git;CNAME;_git2")
-            });
+                context.WyamSettings.OutputPath = publishFolder;
+                context.WyamSettings.NoClean = true;
+                context.Wyam(context.WyamSettings);
+            }
 
-            if (context.GitHasUncommitedChanges(publishFolder))
-            {
-                context.Information("Stage all changes...");
-                context.GitAddAll(publishFolder);
+            if (!context.GitHasUncommitedChanges(publishFolder)) return;
 
-                if (context.GitHasStagedChanges(publishFolder))
-                {
-                    context.Information("Commit all changes...");
-                    context.GitCommit(
-                        publishFolder,
-                        sourceCommit.Committer.Name,
-                        sourceCommit.Committer.Email,
-                        $"Continuous Integration Publish: {sourceCommit.Sha}\r\n{sourceCommit.Message}"
-                    );
+            context.Information("Stage all changes...");
+            context.GitAddAll(publishFolder);
 
-                    PublishToGitHub(context, publishFolder, publishBranchName);
-                }
-            }
+            if (!context.GitHasStagedChanges(publishFolder)) return;
+
+            context.Information("Commit all changes...");
+            context.GitCommit(
+                publishFolder,
+                sourceCommit.Committer.Name,
+                sourceCommit.Committer.Email,
+                $"Continuous Integration Publish: {sourceCommit.Sha}\r\n{sourceCommit.Message}"
+            );
+
+            PublishToGitHub(context, publishFolder, publishBranchName);
         }
-        
+
         private static void PublishToGitHub(BuildContext context, DirectoryPath publishFolder, string publishBranchName)
         {
             var username = context.Credentials?.GitHub?.UserName;