switched docs to running on Statiq

.build/statiq-docs.cake

@@ -0,0 +1,175 @@
+///////////////////////////////////////////////////////////////////////////////
+// DISABLE WYAM
+///////////////////////////////////////////////////////////////////////////////
+
+BuildParameters.Tasks.PreviewDocumentationTask.WithCriteria(() => false, "Favor Statiq over Wyam");
+BuildParameters.Tasks.PublishDocumentationTask.WithCriteria(() => false, "Favor Statiq over Wyam");
+BuildParameters.Tasks.ForcePublishDocumentationTask.WithCriteria(() => false, "Favor Statiq over Wyam");
+
+///////////////////////////////////////////////////////////////////////////////
+// TASK DEFINITIONS
+///////////////////////////////////////////////////////////////////////////////
+
+// No Clean task, we re-use the one provided in Wyam.cake
+
+BuildParameters.Tasks.PublishDocumentationTask = Task("Publish-StatiqDocs")
+    .IsDependentOn("Clean-Documentation")
+    .WithCriteria(() => BuildParameters.ShouldGenerateDocumentation, "Statiq documentation has been disabled")
+    .WithCriteria(() => DirectoryExists(BuildParameters.WyamRootDirectoryPath), "Statiq documentation directory is missing")
+    .Does(() => {
+        // ensure submodules are in place
+        var gitTool = Context.Tools.Resolve("git");
+        if (gitTool == null)
+        {
+            gitTool = Context.Tools.Resolve("git.exe");
+        }
+        if (gitTool == null)
+        {
+            throw new FileNotFoundException("git/git.exe could not be found!");
+        }
+
+        var exitCode = Context.StartProcess(
+            gitTool,
+            new ProcessSettings {
+                Arguments = "submodule update --init --recursive",
+            }
+        );
+
+        // 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 = BuildParameters.WyamRootDirectoryPath.GetDirectoryName();
+
+        var pathsToTestAgainst = new List<string>() {
+            string.Format("{0}{1}", wyamDocsFolderDirectoryName, "/input/")
+        };
+
+        if (BuildParameters.ShouldDocumentSourceFiles)
+        {
+            // BuildParameters.WyamSourceFiles can not be used - the wyam globs are different from globs in GetFiles().
+            pathsToTestAgainst.Add(string.Format("{0}{1}", BuildParameters.SourceDirectoryPath.FullPath, '/'));
+        }
+
+        Verbose("Comparing all file-changes to the following paths:");
+        foreach(var p in pathsToTestAgainst)
+        {
+            Verbose(" - "+p);
+        }
+
+        foreach (var file in filesChanged)
+        {
+            Verbose("Changed File OldPath: {0}, Path: {1}", file.OldPath, file.Path);
+            if (pathsToTestAgainst.Any(x => file.OldPath.Contains(x) || file.Path.Contains(x)))
+            {
+                docFileChanged = true;
+                break;
+            }
+        }
+
+        if (docFileChanged)
+        {
+            Information("Detected that documentation files have changed, so running Statiq...");
+
+            Statiq();
+            PublishStatiqDocs();
+        }
+        else
+        {
+            Information("No documentation has changed, so no need to generate documentation");
+        }
+    }
+)
+.OnError(exception =>
+{
+    Error(exception.Message);
+    Information("Publish-StatiqDocs Task failed, but continuing with next Task...");
+    publishingError = true;
+});
+
+BuildParameters.Tasks.PreviewDocumentationTask = Task("Preview-StatiqDocs")
+    .WithCriteria(() => DirectoryExists(BuildParameters.WyamRootDirectoryPath), "Statiq documentation directory is missing")
+    .Does(() => {
+        Statiq("preview");
+    });
+
+
+BuildParameters.Tasks.ForcePublishDocumentationTask = Task("Force-Publish-StatiqDocs")
+    .IsDependentOn("Clean-Documentation")
+    .WithCriteria(() => DirectoryExists(BuildParameters.WyamRootDirectoryPath), "Statiq documentation directory is missing")
+    .Does(() => {
+        Statiq();
+        PublishStatiqDocs();
+    }
+);
+
+public void PublishStatiqDocs()
+{
+    var canPublishToGitHub =
+                !string.IsNullOrEmpty(BuildParameters.Wyam.AccessToken) &&
+                !string.IsNullOrEmpty(BuildParameters.Wyam.DeployBranch) &&
+                !string.IsNullOrEmpty(BuildParameters.RepositoryOwner) &&
+                !string.IsNullOrEmpty(BuildParameters.RepositoryName);
+
+    if (!canPublishToGitHub)
+    {
+        Warning("Unable to publish documentation, as not all Statiq configuration is present");
+        return;
+    }
+
+    Statiq("deploy");
+}
+
+// TODO: Do we need Cake.Statiq ?
+public void Statiq(string command = "", IDictionary<string, string> additionalSetting = null)
+{
+    var statiqProj = BuildParameters.WyamRootDirectoryPath.CombineWithFilePath("Docs.csproj").FullPath; // TODO: Configurable!
+    var settings = new Dictionary<string, string>
+    {
+        { "Host", BuildParameters.WebHost },
+        { "LinkRoot", BuildParameters.WebLinkRoot },
+        { "BaseEditUrl", BuildParameters.WebBaseEditUrl },
+        { "Title", BuildParameters.Title },
+        { "IncludeGlobalNamespace", "false" },
+        { "STATIQ_DEPLOY_OWNER", BuildParameters.RepositoryOwner },
+        { "STATIQ_DEPLOY_REPO_NAME", BuildParameters.RepositoryName }
+    };
+
+    if (BuildParameters.ShouldDocumentSourceFiles)
+    {
+        settings.Add("SourceFiles", BuildParameters.WyamSourceFiles);
+    }
+
+    if(additionalSetting != null)
+    {
+        settings = new[]{settings, additionalSetting}.SelectMany(x => x).ToDictionary(kvp => kvp.Key, kvp => kvp.Value);
+    }
+
+    if((command.EqualsIgnoreCase("preview") || command.EqualsIgnoreCase("serve")) && !string.IsNullOrEmpty(BuildParameters.WebLinkRoot))
+    {
+        command += $" --virtual-dir={BuildParameters.WebLinkRoot}";
+    }
+
+    // TODO: Read log-level from Env/commandline?
+
+    DotNetCoreRun(statiqProj, new DotNetCoreRunSettings
+    {
+        EnvironmentVariables = settings,
+        ArgumentCustomization = args=>args
+                                .Append(" -- ")
+                                .Append(command)
+                                .Append($"--root=\"{BuildParameters.WyamRootDirectoryPath}\""),
+    });
+}
+
+
+///////////////////////////////////////////////////////////////////////////////
+// BAKE STATIQ IN Cake.Recipe
+///////////////////////////////////////////////////////////////////////////////
+
+BuildParameters.Tasks.PreviewTask.IsDependentOn("Preview-StatiqDocs");
+BuildParameters.Tasks.PublishDocsTask.IsDependentOn("Force-Publish-StatiqDocs");
+BuildParameters.Tasks.ContinuousIntegrationTask.IsDependentOn("Publish-StatiqDocs");

.github/workflows/build.yml

@@ -41,6 +41,7 @@ jobs:
       WYAM_ACCESS_TOKEN: ${{ secrets.WYAM_ACCESS_TOKEN }}
       WYAM_DEPLOY_BRANCH: "gh-pages"
       WYAM_DEPLOY_REMOTE: ${{ github.event.repository.html_url }}
+      STATIQ_DEPLOY_OWNER: "cake-contrib"
 
     steps:
       - name: Checkout the repository

.github/workflows/publishDocs.yml

@@ -4,10 +4,10 @@ on:
   workflow_dispatch:
 
 env:
-  WYAM_ACCESS_TOKEN: ${{ secrets.API_TOKEN }}
-  # secrets.GITHUB_TOKEN has no permissions to push, sadly.
-  WYAM_DEPLOY_BRANCH: 'gh-pages'
-  WYAM_DEPLOY_REMOTE: "${{ github.event.repository.html_url }}"
+  STATIQ_DEPLOY_OWNER: "cake-contrib"
+  WYAM_ACCESS_TOKEN: ${{ secrets.WYAM_ACCESS_TOKEN }}
+  WYAM_DEPLOY_BRANCH: "gh-pages"
+  WYAM_DEPLOY_REMOTE: ${{ github.event.repository.html_url }}
 
 jobs:
   cake:
@@ -20,16 +20,19 @@ jobs:
     - name: Fetch all tags and branches
       run: git fetch --prune --unshallow
 
+    - uses: actions/[email protected]
+      with:
+        dotnet-version: 7.0.x
+
     - name: Cache Tools
       uses: actions/cache@v3
       with:
         path: tools
         key: ${{ runner.os }}-doc-tools-${{ hashFiles('recipe.cake') }}
 
-    - name: Publishing documentaiton
+    - name: Publishing documentation
       uses: cake-build/cake-action@v1
       with:
         script-path: recipe.cake
-        target: Force-Publish-Documentation
-        verbosity: Diagnostic
+        target: PublishDocs
         cake-version: tool-manifest

.gitignore

@@ -52,3 +52,5 @@ docs/input/tasks/*
 # Wyam related
 config.wyam.*
 .idea/
+docs/cache/
+docs/output/

.gitmodules

@@ -0,0 +1,4 @@
+[submodule "docs/theme"]
+	path = docs/theme
+	url = https://github.com/statiqdev/Docable.git
+    branch = main

docs/Docs.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net7.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <LanguageVersion>latest</LanguageVersion>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Statiq.Docs" Version="1.0.0-beta.14" />
+  </ItemGroup>
+
+</Project>

docs/Program.cs

@@ -0,0 +1,10 @@
+await Bootstrapper
+  .Factory
+  .CreateDocs(args)
+  .DeployToGitHubPagesBranch(
+    Config.FromSetting<string>("STATIQ_DEPLOY_OWNER"),
+    Config.FromSetting<string>("WYAM_DEPLOY_REMOTE"),
+    Config.FromSetting<string>("WYAM_ACCESS_TOKEN"),
+    Config.FromSetting<string>("WYAM_DEPLOY_BRANCH")
+  )
+  .RunAsync();

docs/input/assets/favicons/README.md

@@ -0,0 +1,4 @@
+# FAVICON package
+
+This was all generated by using https://realfavicongenerator.net/ with
+https://github.com/cake-contrib/graphics/blob/3344c5e09d33dedb984edf8a362d8a3d32f7acd4/png/addin/cake-contrib-addin-large.png as the source.

docs/input/assets/favicons/browserconfig.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="utf-8"?>
+<browserconfig>
+    <msapplication>
+        <tile>
+            <square150x150logo src="/mstile-150x150.png"/>
+            <TileColor>#da532c</TileColor>
+        </tile>
+    </msapplication>
+</browserconfig>

docs/input/assets/favicons/site.webmanifest

@@ -0,0 +1,19 @@
+{
+    "name": "CakeContrib/Cake.7zip",
+    "short_name": "Cake.7zip",
+    "icons": [
+        {
+            "src": "/android-chrome-192x192.png",
+            "sizes": "192x192",
+            "type": "image/png"
+        },
+        {
+            "src": "/android-chrome-512x512.png",
+            "sizes": "512x512",
+            "type": "image/png"
+        }
+    ],
+    "theme_color": "#ffffff",
+    "background_color": "#ffffff",
+    "display": "standalone"
+}

docs/input/index.cshtml

@@ -4,40 +4,41 @@ NoSidebar: true
 NoContainer: false
 NoGutter: true
 ---
-<script>
-if(!document.location.href.endsWith("/")){
-  document.location.href = document.location.href + "/"; // or else the relative hyperlinks won't work...
-}
-</script>
-<div class="container">				
+<div class="container">
 	<h1>What is it?</h1>
     <p>
-        Cake.7zip is an Addin for <a href="http://cakebuild.net/">Cake</a> to use <a href="https://www.7-zip.org/">7Zip</a>.
+        Cake.7zip is an Addin for <a href="https://cakebuild.net/">Cake</a> to use <a href="https://www.7-zip.org/">7Zip</a>.
     </p>
 </div>
 <div class="container">
 	<h1>Usage</h1>
   <div>
   <h2>Usage in Cake</H2>
     <p>
-        Have a look at <a href="api/Cake.SevenZip/SevenZipAliases/">SevenZipAliases</a> on how to integrate with <a href="http://cakebuild.net/">Cake</a>. There are also some examples there.
+        Have a look at <a [email protected]("/api/Cake.SevenZip/SevenZipAliases/")>SevenZipAliases</a>
+        on how to integrate with <a href="https://cakebuild.net/">Cake</a>. There are also some examples there.
     </p>
   </div>
   <div>
   <h2>Available Commands</H2>
     <p>
-        All available commands are listed at the <a href="api/Cake.SevenZip.Commands/ICommand/">ICommand</a>-Interface.
+        All available commands are listed at the
+        <a [email protected]("/api/Cake.SevenZip.Commands/ICommand/")>ICommand</a>-Interface.
     </p>
   </div>
   <div>
   <h2>Available Switches</H2>
     <p>
-        All available switches are listed at the <a href="api/Cake.SevenZip.Switches/ISupportSwitch/">ISupportSwitch</a>-Interface. However, not all commands support every switch.
+        All available switches are listed at the
+        <a [email protected]("/api/Cake.SevenZip.Switches/ISupportSwitch/")>ISupportSwitch</a>-Interface.
+        However, not all commands support every switch.
     </p>
   </div>
   <h2>Available Arguments</H2>
     <p>
-        All available arguments are listed at the <a href="api/Cake.SevenZip.Commands/IHaveArgument/">IHaveArgument</a>-Interface. However, not all commands support every argument.
+        All available arguments are listed at the
+        <a [email protected]("/api/Cake.SevenZip.Arguments/IHaveArgument/")>IHaveArgument</a>-Interface.
+        However, not all commands support every argument.
     </p>
   </div>
 </div>