Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

switched docs to running on Statiq #233

Draft
wants to merge 2 commits into
base: develop
Choose a base branch
from
Draft
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
switched docs to running on Statiq
  • Loading branch information
nils-a committed Sep 3, 2023
commit 91be63e65075c6d1d74496c1fa9a69f9ed1acba0
175 changes: 175 additions & 0 deletions .build/statiq-docs.cake
Original file line number Diff line number Diff line change
@@ -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");
1 change: 1 addition & 0 deletions .github/workflows/build.yml
Original file line number Diff line number Diff line change
@@ -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
17 changes: 10 additions & 7 deletions .github/workflows/publishDocs.yml
Original file line number Diff line number Diff line change
@@ -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
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -52,3 +52,5 @@ docs/input/tasks/*
# Wyam related
config.wyam.*
.idea/
docs/cache/
docs/output/
3 changes: 3 additions & 0 deletions .gitmodules
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
[submodule "docs/theme"]
path = docs/theme
url = https://github.com/statiqdev/Docable.git
15 changes: 15 additions & 0 deletions docs/Docs.csproj
Original file line number Diff line number Diff line change
@@ -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>
10 changes: 10 additions & 0 deletions docs/Program.cs
Original file line number Diff line number Diff line change
@@ -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();
4 changes: 4 additions & 0 deletions docs/input/assets/favicons/README.md
Original file line number Diff line number Diff line change
@@ -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.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/input/assets/favicons/apple-touch-icon.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
9 changes: 9 additions & 0 deletions docs/input/assets/favicons/browserconfig.xml
Original file line number Diff line number Diff line change
@@ -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>
Binary file added docs/input/assets/favicons/favicon-16x16.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/input/assets/favicons/favicon-32x32.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/input/assets/favicons/favicon.ico
Binary file not shown.
Binary file added docs/input/assets/favicons/mstile-150x150.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
33 changes: 33 additions & 0 deletions docs/input/assets/favicons/safari-pinned-tab.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
19 changes: 19 additions & 0 deletions docs/input/assets/favicons/site.webmanifest
Original file line number Diff line number Diff line change
@@ -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"
}
23 changes: 12 additions & 11 deletions docs/input/index.cshtml
Original file line number Diff line number Diff line change
@@ -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>
Empty file removed docs/settings.yml
Empty file.
1 change: 1 addition & 0 deletions docs/theme
Submodule theme added at 58c608
1 change: 1 addition & 0 deletions recipe.cake
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
#load nuget:?package=Cake.Recipe&version=3.1.1
#l ./.build/statiq-docs.cake

Environment.SetVariableNames();