(GH-1932) Convert to Wyam for Documentation

.gitignore

@@ -85,7 +85,7 @@ _NCrunch_GitVersion
 GitVersion.sln.ide/
 .vs/
 Packages/
-build/
+build/*
 site/
 /TestResult.xml
 
@@ -123,3 +123,9 @@ src/GitVersionRubyGem/bin/GitVersion.exe
 src/GitVersionRubyGem/bin/LibGit2Sharp.dll.config
 
 !**/*.cake
+.DS_Store
+
+# Wyam
+config.wyam.dll
+config.wyam.hash
+config.wyam.packages.xml

.markdownlint.json

@@ -0,0 +1,3 @@
+{
+    "MD026": false
+}

.vscode/settings.json

@@ -1,7 +1,8 @@
 {
+    "editor.rulers": [80],
     "cSpell.words": [
         "commiting",
         "gittools",
         "gitversion"
     ]
-}
+}

CONTRIBUTING.md

@@ -88,13 +88,13 @@ We use Cake for our build and deployment process. The way the build / release pr
 1) We build releasable artifacts on AppVeyor
 1) Login to AppVeyor
 1) Deploy the latest master build
-![docs/img/release-1-deploy.png](docs/img/release-1-deploy.png)
+![docs/input/docs/img/release-1-deploy.png](docs/input/docs/img/release-1-deploy.png)
 1) Choose GitVersion release, when you press deploy it will create a *non-released* GitHub release, this *will not* create a Git tag. This step is so we can validate the release and release notes before pushing the button.
-![docs/img/release-2-deploy.png](docs/img/release-2-deploy.png)
+![docs/input/docs/img/release-2-deploy.png](docs/input/docs/img/release-2-deploy.png)
 1) All the artifacts should upload nicely
-![docs/img/release-3-deploy.png](docs/img/release-3-deploy.png)
+![docs/input/docs/img/release-3-deploy.png](docs/input/docs/img/release-3-deploy.png)
 1) Head over to GitHub releases, you should have a draft release, download a copy of the release notes
-![docs/img/release-4-deploy.png](docs/img/release-4-deploy.png)
+![docs/input/docs/img/release-4-deploy.png](docs/input/docs/img/release-4-deploy.png)
 1) Edit the release and do the following:
     1. Remove the build metadata from the tag and title (the + and everything after it)
     2. Paste the downloaded release notes in, you can clean them up if you want otherwise there may be closed issues which were questions etc.

README.md

@@ -1,5 +1,5 @@
 <h1>
-    <img src="docs/img/package_icon.svg" alt="Tree" height="100">
+    <img src="docs/input/docs/img/package_icon.svg" alt="Tree" height="100">
     GitVersion
 </h1>
 
@@ -102,7 +102,7 @@ from The Noun Project.
 [how]:                             http://gitversion.readthedocs.org/en/latest/more-info/how-it-works/
 [faq]:                             http://gitversion.readthedocs.org/en/latest/faq/
 [who]:                             http://gitversion.readthedocs.org/en/latest/who/
-[gv-in-action]:                    https://raw.github.com/GitTools/GitVersion/master/docs/img/README.png
+[gv-in-action]:                    https://raw.github.com/GitTools/GitVersion/master/docs/input/docs/img/README.png
 [dockerhub]:                       https://hub.docker.com/r/gittools/gitversion/
 [dockerhub-badge]:                 https://img.shields.io/docker/pulls/gittools/gitversion.svg
 [az-pipeline-task]:                https://marketplace.visualstudio.com/items?itemName=GitTools.usegitversion

build.cake

@@ -7,11 +7,14 @@
 #addin "nuget:?package=Cake.Coverlet&version=2.3.4"
 #addin "nuget:?package=Cake.Docker&version=0.10.1"
 #addin "nuget:?package=Cake.Gem&version=0.8.1"
+#addin "nuget:?package=Cake.Git&version=0.21.0"
 #addin "nuget:?package=Cake.Gitter&version=0.11.1"
 #addin "nuget:?package=Cake.Incubator&version=5.1.0"
 #addin "nuget:?package=Cake.Json&version=4.0.0"
+#addin "nuget:?package=Cake.Kudu&version=0.10.1"
 #addin "nuget:?package=Cake.Npm&version=0.17.0"
 #addin "nuget:?package=Cake.Tfx&version=0.9.1"
+#addin "nuget:?package=Cake.Wyam&version=2.2.9"
 
 #addin "nuget:?package=Newtonsoft.Json&version=12.0.2"
 #addin "nuget:?package=SharpZipLib&version=1.2.0"
@@ -20,6 +23,8 @@
 // Install tools.
 #tool "nuget:?package=NUnit.ConsoleRunner&version=3.10.0"
 #tool "nuget:?package=nuget.commandline&version=5.2.0"
+#tool "nuget:?package=Wyam&version=2.2.9"
+#tool "nuget:?package=KuduSync.NET&version=1.5.2"
 
 // Install .NET Core Global tools.
 #tool "dotnet:?package=Codecov.Tool&version=1.7.2"
@@ -34,6 +39,7 @@
 #load "./build/artifacts-test.cake"
 #load "./build/docker.cake"
 #load "./build/publish.cake"
+#load "./build/wyam.cake"
 
 using Xunit;
 using System.Diagnostics;
@@ -140,6 +146,7 @@ Task("Publish")
     .IsDependentOn("Publish-NuGet")
     .IsDependentOn("Publish-Chocolatey")
     .IsDependentOn("Publish-Gem")
+    .IsDependentOn("Publish-Documentation")
     .Finally(() =>
 {
     if (publishingError)

build/utils/paths.cake

@@ -25,6 +25,7 @@ public class BuildPaths
 
         var semVersion = version.SemVersion;
 
+        var sourceDir                     = (DirectoryPath)(context.Directory("./src"));
         var artifactsDir                  = (DirectoryPath)(context.Directory("./artifacts") + context.Directory("v" + semVersion));
         var artifactsBinDir               = artifactsDir.Combine("bin");
         var artifactsBinPortableDir       = artifactsBinDir.Combine("portable");
@@ -42,6 +43,7 @@ public class BuildPaths
 
         // Directories
         var buildDirectories = new BuildDirectories(
+            sourceDir,
             artifactsDir,
             nativeDir,
             buildArtifactDir,
@@ -86,6 +88,7 @@ public class BuildFiles
 
 public class BuildDirectories
 {
+    public DirectoryPath Source { get; private set; }
     public DirectoryPath Artifacts { get; private set; }
     public DirectoryPath Native { get; private set; }
     public DirectoryPath NugetRoot { get; private set; }
@@ -100,6 +103,7 @@ public class BuildDirectories
     public ICollection<DirectoryPath> ToClean { get; private set; }
 
     public BuildDirectories(
+        DirectoryPath sourceDir,
         DirectoryPath artifactsDir,
         DirectoryPath nativeDir,
         DirectoryPath buildArtifactDir,
@@ -113,6 +117,7 @@ public class BuildDirectories
         DirectoryPath artifactsBinFullFx472Dir
         )
     {
+        Source = sourceDir;
         Artifacts = artifactsDir;
         Native = nativeDir;
         BuildArtifact = buildArtifactDir;

build/wyam.cake

@@ -0,0 +1,160 @@
+Task("Clean-Documentation")
+    .Does(() =>
+{
+    EnsureDirectoryExists(MakeAbsolute(Directory("artifacts/temp/_PublishedDocumentation")));
+});
+
+Task("Preview-Documentation")
+    .WithCriteria(() => DirectoryExists(MakeAbsolute(Directory("docs"))), "Wyam documentation directory is missing")
+    .Does<BuildParameters>((parameters) =>
+{
+    Wyam(new WyamSettings
+    {
+        Recipe = "Docs",
+        Theme = "Samson",
+        OutputPath = MakeAbsolute(Directory("artifacts/Documentation")),
+        RootPath = MakeAbsolute(Directory("docs")),
+        Preview = true,
+        Watch = true,
+        ConfigurationFile = MakeAbsolute((FilePath)"config.wyam"),
+        PreviewVirtualDirectory = "GitVersion",
+        Settings = new Dictionary<string, object>
+        {
+            { "Host",  "gittools.github.io" },
+            { "LinkRoot",  "GitVersion" },
+            { "BaseEditUrl", "https://github.com/gittools/GitVersion/tree/master/docs/input/" },
+            { "SourceFiles", MakeAbsolute(parameters.Paths.Directories.Source) + "/**/{!bin,!obj,!packages,!*.Tests,}/**/*.cs" },
+            { "Title", "GitVersion" },
+            { "IncludeGlobalNamespace", false }
+        }
+    });
+});
+
+Task("Force-Publish-Documentation")
+    .IsDependentOn("Clean-Documentation")
+    .WithCriteria(() => DirectoryExists(MakeAbsolute(Directory("docs"))), "Wyam documentation directory is missing")
+    .Does<BuildParameters>((parameters) =>
+{
+    Wyam(new WyamSettings
+    {
+        Recipe = "Docs",
+        Theme = "Samson",
+        OutputPath = MakeAbsolute(Directory("artifacts/Documentation")),
+        RootPath = MakeAbsolute(Directory("docs")),
+        ConfigurationFile = MakeAbsolute((FilePath)"config.wyam"),
+        PreviewVirtualDirectory = "GitVersion",
+        Settings = new Dictionary<string, object>
+        {
+            { "Host",  "gittools.github.io" },
+            { "LinkRoot",  "GitVersion" },
+            { "BaseEditUrl", "https://github.com/gittools/GitVersion/tree/master/docs/input/" },
+            { "SourceFiles", MakeAbsolute(parameters.Paths.Directories.Source) + "/**/{!bin,!obj,!packages,!*.Tests,}/**/*.cs" },
+            { "Title", "GitVersion" },
+            { "IncludeGlobalNamespace", false }
+        }
+    });
+
+    PublishDocumentation(parameters);
+});
+
+Task("Publish-Documentation")
+    .IsDependentOn("Clean-Documentation")
+    .WithCriteria(() => DirectoryExists(MakeAbsolute(Directory("docs"))), "Wyam documentation directory is missing")
+    .WithCriteria<BuildParameters>((context, parameters) => parameters.IsRunningOnWindows,       "Publish-Documentation is ran only on Windows agents.")
+    .WithCriteria<BuildParameters>((context, parameters) => parameters.IsRunningOnAzurePipeline, "Publish-Documentation is ran only on AzurePipeline.")
+    .WithCriteria<BuildParameters>((context, parameters) => !parameters.IsPullRequest, "Publish-Documentation works only for non-PR commits.")
+    .Does<BuildParameters>((parameters) =>
+{
+    // Check to see if any documentation has changed
+    var sourceCommit = GitLogTip("./");
+    Information("Source Commit Sha: {0}", sourceCommit.Sha);
+    var filesChanged = GitDiff("./", sourceCommit.Sha);
+    Information("Number of changed files: {0}", filesChanged.Count);
+    var docFileChanged = false;
+
+    var wyamDocsFolderDirectoryName = "docs";
+
+    foreach (var file in filesChanged)
+    {
+        var forwardSlash = '/';
+        Verbose("Changed File OldPath: {0}, Path: {1}", file.OldPath, file.Path);
+        if (file.OldPath.Contains(string.Format("{0}{1}", wyamDocsFolderDirectoryName, forwardSlash)) ||
+            file.Path.Contains(string.Format("{0}{1}", wyamDocsFolderDirectoryName, forwardSlash)) ||
+            file.Path.Contains("config.wyam"))
+        {
+        docFileChanged = true;
+        break;
+        }
+    }
+
+    if (docFileChanged)
+    {
+        Information("Detected that documentation files have changed, so running Wyam...");
+
+        Wyam(new WyamSettings
+        {
+            Recipe = "Docs",
+            Theme = "Samson",
+            OutputPath = MakeAbsolute(Directory("artifacts/Documentation")),
+            RootPath = MakeAbsolute(Directory("docs")),
+            ConfigurationFile = MakeAbsolute((FilePath)"config.wyam"),
+            PreviewVirtualDirectory = "GitVersion",
+            Settings = new Dictionary<string, object>
+            {
+                { "Host",  "gittools.github.io" },
+                { "LinkRoot",  "GitVersion" },
+                { "BaseEditUrl", "https://github.com/gittools/GitVersion/tree/master/docs/input/" },
+                { "SourceFiles", MakeAbsolute(parameters.Paths.Directories.Source) + "/**/{!bin,!obj,!packages,!*.Tests,}/**/*.cs" },
+                { "Title", "GitVersion" },
+                { "IncludeGlobalNamespace", false }
+            }
+        });
+
+        PublishDocumentation(parameters);
+    }
+    else
+    {
+        Information("No documentation has changed, so no need to generate documentation");
+    }
+})
+.OnError(exception =>
+{
+    Error(exception.Message);
+    Information("Publish-Documentation Task failed, but continuing with next Task...");
+    publishingError = true;
+});
+
+public void PublishDocumentation(BuildParameters parameters)
+{
+    var sourceCommit = GitLogTip("./");
+
+    var publishFolder = MakeAbsolute(Directory("artifacts/temp/_PublishedDocumentation")).Combine(DateTime.Now.ToString("yyyyMMdd_HHmmss"));
+    Information("Publishing Folder: {0}", publishFolder);
+    Information("Getting publish branch...");
+    GitClone("https://github.com/gittools/GitVersion", publishFolder, new GitCloneSettings{ BranchName = "gh-pages" });
+
+    Information("Sync output files...");
+    Kudu.Sync(MakeAbsolute(Directory("artifacts/Documentation")), publishFolder, new KuduSyncSettings {
+        ArgumentCustomization = args=>args.Append("--ignore").AppendQuoted(".git;CNAME")
+    });
+
+    if (GitHasUncommitedChanges(publishFolder))
+    {
+        Information("Stage all changes...");
+        GitAddAll(publishFolder);
+
+        if (GitHasStagedChanges(publishFolder))
+        {
+            Information("Commit all changes...");
+            GitCommit(
+                publishFolder,
+                sourceCommit.Committer.Name,
+                sourceCommit.Committer.Email,
+                string.Format("Continuous Integration Publish: {0}\r\n{1}", sourceCommit.Sha, sourceCommit.Message)
+            );
+
+            Information("Pushing all changes...");
+            GitPush(publishFolder, parameters.Credentials.GitHub.Token, "x-oauth-basic", "gh-pages");
+        }
+    }
+}

config.wyam

@@ -0,0 +1 @@
+Pipelines["RenderPages"].Replace("WriteMetadata", new Headings(2));