`Statiq.Docs` run exception caused by Docable theme compilation error #150

BryanWilhite · 2022-06-26T03:25:50Z

BryanWilhite
Jun 26, 2022

This is going to be lengthy and I apologize. When I run Statiq.Docs I am getting this error:

 Content/PostProcess » RenderContentPostProcessTemplates

…

_ViewImports.cshtml(7,7): error CS0246: The type or namespace name 'Docable' could not be found (are you missing a using directive or an assembly reference?)

The VSCode task running Statiq.Docs.Shell:

{
	"label": "dotnet run [Statiq]",
	"command": "dotnet",
	"type": "shell",
	"args": [
		"run",
		"--project",
		"${workspaceFolder}/Statiq.Docs.Shell/Statiq.Docs.Shell.csproj",
		"--configuration",
		"Release",
		"--",
		"--root",
		"${workspaceFolder}/statiq-root",
		"--log-level",
		"Information",
		"--log-file",
		"${workspaceFolder}/statiq-root/statiq-"
	],
	"problemMatcher": "$msCompile"
},

The Bootstrapper statement:

await Bootstrapper
    .Factory
    .CreateDocs(args)
    //.SetThemePath("../../../Statiq.Themes.Docable")
    .AddExcludedPath("../Statiq.Docs.Shell")
    .AddSettings(new Dictionary<string, object>
    {
        { DocsKeys.ApiPath, "api" },
        {
            DocsKeys.SourceFiles,
            new []
            {
                "../../../../SonghayCore/**/{!.git,!bin,!obj,!packages,!*.Tests,}/**/*.cs",
                "../../../../SonghayCore.xUnit/**/{!.git,!bin,!obj,!packages,!*.Tests,}/**/*.cs",
            }
        },
        { DocsKeys.OutputApiDocuments, true },
        { WebKeys.Author, "@BryanWilhite" },
        { WebKeys.Copyright, $"(c) {DateTime.Now.Year} Songhay System" },
        { WebKeys.GitHubName, "Bryan Wilhite" },
        { WebKeys.GitHubUsername, "BryanWilhite" },
        { WebKeys.OutputPath, "../docs-statiq" },
    })
    .RunAsync();

The GitHub repo layout:

Log file:

2022-06-25 17:47:20.054 -07:00 [Information] Statiq.Core.Engine: Statiq Framework version 1.0.0-beta.60+ea55317a9a78127a162a36ff396a08bb175c219a
2022-06-25 17:47:20.164 -07:00 [Information] Statiq.Core.Engine: Statiq Web version 1.0.0+a55f7625956da18068ece3dbab3b0819cc2937d0
2022-06-25 17:47:20.164 -07:00 [Information] Statiq.Core.Engine: Statiq Docs version 1.0.0-beta.3+8f1e796a94119c5d824f75505cf674122cfa3dfe
2022-06-25 17:47:20.174 -07:00 [Information] Statiq.App.Bootstrapper: Root path:
       /home/rasx/sourceRoot/SonghayCore/statiq-root
2022-06-25 17:47:20.176 -07:00 [Information] Statiq.App.Bootstrapper: Input path(s):
       theme/input
       input
2022-06-25 17:47:20.177 -07:00 [Information] Statiq.App.Bootstrapper: Excluded path(s):
       ../Statiq.Docs.Shell
2022-06-25 17:47:20.177 -07:00 [Information] Statiq.App.Bootstrapper: Output path:
       ../docs-statiq
2022-06-25 17:47:20.177 -07:00 [Information] Statiq.App.Bootstrapper: Temp path:
       temp
2022-06-25 17:47:20.177 -07:00 [Information] Statiq.App.Bootstrapper: Cache path:
       cache
2022-06-25 17:47:20.195 -07:00 [Information] Statiq.Core.Engine: ========== Execution ==========
2022-06-25 17:47:20.196 -07:00 [Information] Statiq.Core.Engine: Executing 13 pipelines (AnalyzeContent, Api, Archives, Assets, Code, Content, Data, DirectoryMetadata, Feeds, Inputs, Redirects, SearchIndex, Sitemap)
2022-06-25 17:47:20.208 -07:00 [Information] Statiq.Core.Engine: Cleaned temp directory /home/rasx/sourceRoot/SonghayCore/statiq-root/temp
2022-06-25 17:47:20.245 -07:00 [Information] Statiq.Core.Engine: Restored write tracking data from /home/rasx/sourceRoot/SonghayCore/statiq-root/cache/writecache.json
2022-06-25 17:47:20.371 -07:00 [Information] Statiq.Core.Engine: Restored Razor compilation cache from /home/rasx/sourceRoot/SonghayCore/statiq-root/cache/razorcache.json with 2 assemblies
2022-06-25 17:47:20.380 -07:00 [Information] Statiq.Core.Engine: -> Inputs/Input » Starting Inputs Input phase execution... (0 input document(s), 1 module(s))
2022-06-25 17:47:20.380 -07:00 [Information] Statiq.Core.Engine: -> DirectoryMetadata/Input » Starting DirectoryMetadata Input phase execution... (0 input document(s), 1 module(s))
2022-06-25 17:47:20.380 -07:00 [Information] Statiq.Core.Engine: -> Code/Input » Starting Code Input phase execution... (0 input document(s), 1 module(s))
2022-06-25 17:47:20.547 -07:00 [Information] Statiq.Core.Engine: <- Inputs/Input » Finished Inputs Input phase execution (9 output document(s), 166 ms)
2022-06-25 17:47:20.547 -07:00 [Information] Statiq.Core.Engine: <- DirectoryMetadata/Input » Finished DirectoryMetadata Input phase execution (0 output document(s), 167 ms)
2022-06-25 17:47:20.550 -07:00 [Information] Statiq.Core.Engine: -> DirectoryMetadata/Process » Starting DirectoryMetadata Process phase execution... (0 input document(s), 1 module(s))
2022-06-25 17:47:20.555 -07:00 [Information] Statiq.Core.Engine: <- DirectoryMetadata/Process » Finished DirectoryMetadata Process phase execution (0 output document(s), 4 ms)
2022-06-25 17:47:20.555 -07:00 [Information] Statiq.Core.Engine: -> Inputs/Process » Starting Inputs Process phase execution... (9 input document(s), 8 module(s))
2022-06-25 17:47:20.741 -07:00 [Information] Statiq.Core.Engine: <- Inputs/Process » Finished Inputs Process phase execution (9 output document(s), 185 ms)
2022-06-25 17:47:20.741 -07:00 [Information] Statiq.Core.Engine: -> Assets/Process » Starting Assets Process phase execution... (0 input document(s), 3 module(s))
2022-06-25 17:47:20.741 -07:00 [Information] Statiq.Core.Engine: -> Data/Process » Starting Data Process phase execution... (0 input document(s), 5 module(s))
2022-06-25 17:47:20.766 -07:00 [Information] Statiq.Core.Engine: <- Data/Process » Finished Data Process phase execution (0 output document(s), 25 ms)
2022-06-25 17:47:21.037 -07:00 [Information] Statiq.Core.Engine: <- Code/Input » Finished Code Input phase execution (198 output document(s), 656 ms)
2022-06-25 17:47:21.037 -07:00 [Information] Statiq.Core.Engine: -> Api/Process » Starting Api Process phase execution... (0 input document(s), 1 module(s))
2022-06-25 17:47:21.250 -07:00 [Information] Statiq.Core.Engine: <- Assets/Process » Finished Assets Process phase execution (5 output document(s), 508 ms)
2022-06-25 17:47:23.322 -07:00 [Information] Statiq.Core.Engine: <- Api/Process » Finished Api Process phase execution (1317 output document(s), 2284 ms)
2022-06-25 17:47:23.322 -07:00 [Information] Statiq.Core.Engine: -> Content/Process » Starting Content Process phase execution... (0 input document(s), 4 module(s))
2022-06-25 17:47:23.943 -07:00 [Information] Statiq.Core.Engine: <- Content/Process » Finished Content Process phase execution (1319 output document(s), 620 ms)
2022-06-25 17:47:23.943 -07:00 [Information] Statiq.Core.Engine: -> Archives/Process » Starting Archives Process phase execution... (0 input document(s), 3 module(s))
2022-06-25 17:47:23.943 -07:00 [Information] Statiq.Core.Engine: -> Redirects/Process » Starting Redirects Process phase execution... (0 input document(s), 2 module(s))
2022-06-25 17:47:23.959 -07:00 [Information] Statiq.Core.Engine: <- Redirects/Process » Finished Redirects Process phase execution (0 output document(s), 15 ms)
2022-06-25 17:47:26.475 -07:00 [Information] Statiq.Core.Engine: <- Archives/Process » Finished Archives Process phase execution (1 output document(s), 2531 ms)
2022-06-25 17:47:26.475 -07:00 [Information] Statiq.Core.Engine: -> Feeds/Process » Starting Feeds Process phase execution... (0 input document(s), 3 module(s))
2022-06-25 17:47:26.775 -07:00 [Information] Statiq.Core.Engine: <- Feeds/Process » Finished Feeds Process phase execution (2 output document(s), 299 ms)
2022-06-25 17:47:26.775 -07:00 [Information] Statiq.Core.Engine: -> Data/Output » Starting Data Output phase execution... (0 input document(s), 2 module(s))
2022-06-25 17:47:26.776 -07:00 [Information] Statiq.Core.Engine: -> Sitemap/PostProcess » Starting Sitemap PostProcess phase execution... (0 input document(s), 1 module(s))
2022-06-25 17:47:26.776 -07:00 [Information] Statiq.Core.Engine: -> SearchIndex/PostProcess » Starting SearchIndex PostProcess phase execution... (0 input document(s), 1 module(s))
2022-06-25 17:47:26.776 -07:00 [Information] Statiq.Core.Engine: -> Assets/Output » Starting Assets Output phase execution... (5 input document(s), 2 module(s))
2022-06-25 17:47:26.776 -07:00 [Information] Statiq.Core.Engine: -> Redirects/Output » Starting Redirects Output phase execution... (0 input document(s), 1 module(s))
2022-06-25 17:47:26.776 -07:00 [Information] Statiq.Core.Engine: <- SearchIndex/PostProcess » Finished SearchIndex PostProcess phase execution (0 output document(s), 0 ms)
2022-06-25 17:47:26.776 -07:00 [Information] Statiq.Core.Engine: -> SearchIndex/Output » Starting SearchIndex Output phase execution... (0 input document(s), 1 module(s))
2022-06-25 17:47:26.779 -07:00 [Information] Statiq.Core.Engine: -> Archives/PostProcess » Starting Archives PostProcess phase execution... (1 input document(s), 1 module(s))
2022-06-25 17:47:26.779 -07:00 [Information] Statiq.Core.Engine: -> Content/PostProcess » Starting Content PostProcess phase execution... (1319 input document(s), 1 module(s))
2022-06-25 17:47:26.780 -07:00 [Information] Statiq.Core.Engine: -> Feeds/Output » Starting Feeds Output phase execution... (2 input document(s), 2 module(s))
2022-06-25 17:47:26.781 -07:00 [Information] Statiq.Core.Engine: <- SearchIndex/Output » Finished SearchIndex Output phase execution (0 output document(s), 4 ms)
2022-06-25 17:47:26.781 -07:00 [Information] Statiq.Core.Engine: <- Data/Output » Finished Data Output phase execution (0 output document(s), 6 ms)
2022-06-25 17:47:26.782 -07:00 [Information] Statiq.Core.Engine: <- Redirects/Output » Finished Redirects Output phase execution (0 output document(s), 5 ms)
2022-06-25 17:47:26.791 -07:00 [Information] Statiq.Core.Engine: <- Feeds/Output » Finished Feeds Output phase execution (2 output document(s), 11 ms)
2022-06-25 17:47:26.794 -07:00 [Information] Statiq.Core.Engine: <- Assets/Output » Finished Assets Output phase execution (5 output document(s), 17 ms)
2022-06-25 17:47:26.839 -07:00 [Information] Statiq.Core.Engine: <- Sitemap/PostProcess » Finished Sitemap PostProcess phase execution (1 output document(s), 62 ms)
2022-06-25 17:47:26.839 -07:00 [Information] Statiq.Core.Engine: -> Sitemap/Output » Starting Sitemap Output phase execution... (1 input document(s), 1 module(s))
2022-06-25 17:47:26.855 -07:00 [Information] Statiq.Core.Engine: <- Sitemap/Output » Finished Sitemap Output phase execution (1 output document(s), 15 ms)

Answered by daveaglick

Jun 27, 2022

My first guess is that the bits that find, compile, and reference theme projects at runtime might not be using the Statiq root path like they should be (at least my expectation is that they should be - the theme path should always be allowed to be a sibling of the input path IMO).

If you’re able to, can you try placing a copy of the theme folder under the root folder for the console app? I’m curious if that finds the theme project and fixes the compilation issues.

Otherwise - I’m on vacation this week with limited access and will be happy to look further when I get back next week.

View full answer

daveaglick · 2022-06-27T12:48:22Z

daveaglick
Jun 27, 2022
Maintainer

My first guess is that the bits that find, compile, and reference theme projects at runtime might not be using the Statiq root path like they should be (at least my expectation is that they should be - the theme path should always be allowed to be a sibling of the input path IMO).

If you’re able to, can you try placing a copy of the theme folder under the root folder for the console app? I’m curious if that finds the theme project and fixes the compilation issues.

Otherwise - I’m on vacation this week with limited access and will be happy to look further when I get back next week.

0 replies

BryanWilhite · 2022-07-03T04:57:19Z

BryanWilhite
Jul 3, 2022
Author

`Statiq.Docs`: a tour of what works

The Statiq console project, its Release directory, serves as the --root for the run:

{
	"label": "dotnet Statiq [Release]",
	"command": "dotnet",
	"type": "shell",
	"args": [
		"${workspaceFolder}/Statiq.Docs.Shell/bin/Release/net6.0/Statiq.Docs.Shell.dll",
		"--configuration",
		"Release",
		"--",
		"--root",
		"${workspaceFolder}/Statiq.Docs.Shell/bin/Release/net6.0/",
		"--log-level",
		"Information",
		"--log-file",
		"${workspaceFolder}/Statiq.Docs.Shell/statiq-"
	],
	"options": {
		"cwd": "${workspaceRoot}/Statiq.Docs.Shell/bin/Release/net6.0/"
	},
	"problemMatcher": "$msCompile"
},

The Docable theme is also in this Release folder (this rather inconvenient change is the primary fix):

The theme directory comes from this Visual Studio Code task:

{
	"label": "git [Statiq Theme Docable]",
	"command": "git",
	"type": "shell",
	"args": [
		"submodule",
		"add",
		"--force",
		"[email protected]:statiqdev/Docable.git",
		"${workspaceFolder}/Statiq.Docs.Shell/bin/Release/net6.0/theme/"
	],
	"options": {
		"cwd": "${workspaceRoot}/Statiq.Docs.Shell/bin/Release/net6.0/"
	},
	"problemMatcher": "$msCompile"
},

The Statiq Bootstrapper is adorned fluently with the assumption that output and excluded paths are four directory levels (../../../../) above the Statiq --root:

using Statiq.Common;
using Statiq.App;
using Statiq.Docs;
using Statiq.Web;

await Bootstrapper
    .Factory
    .CreateDocs(args)
    .AddExcludedPath("../../../../Statiq.Docs.Shell")
    .AddSettings(new Dictionary<string, object>
    {
        { Keys.Title, "API" },
        { Keys.LinkRoot, "SonghayCore" },
        { DocsKeys.ApiPath, "latest" },
        {
            DocsKeys.SourceFiles,
            new []
            {
                "../../../../../SonghayCore/**/{!.git,!bin,!obj,!packages,!*.Tests,}/**/*.cs",
                "../../../../../SonghayCore.xUnit/**/{!.git,!bin,!obj,!packages,!*.Tests,}/**/*.cs",
            }
        },
        { DocsKeys.OutputApiDocuments, true },
        { WebKeys.Author, "@BryanWilhite" },
        { WebKeys.Copyright, $"(c) {DateTime.Now.Year} Songhay System" },
        { WebKeys.GitHubName, "Bryan Wilhite" },
        { WebKeys.GitHubUsername, "BryanWilhite" },
        { WebKeys.OutputPath, "../../../../docs" },
    })
    .RunAsync();

What is strange to me is that DocsKeys.SourceFiles must be five directory levels (../../../../../).

Two inconvenient changes are required to get the theme to work correctly:

links starting with /assets/* have to be changed to /SonghayCore/assets/* in /theme/input/_Layout.cshtml (there is an open issue related to this need)
change SiteTitle in /theme/themesettings.yml (this need is well documented)

The final Statiq product is here: https://bryanwilhite.github.io/SonghayCore/latest/

1 reply

daveaglick Jul 7, 2022
Maintainer

Fantastic write-up, thanks! This is a really interesting configuration - I don't think I've seen anyone place the Statiq root inside one of the compilation/bin folders before (the more common scenario is to use dotnet run from the root). I'm actually pretty pleased it worked as well as it did, the changes you needed to make not withstanding.

And about those - it looks like this is where effort needs to be placed on my end:

links starting with /assets/* have to be changed to /SonghayCore/assets/* in /theme/input/_Layout.cshtml

That's definitely annoying - I'll get it patched right now! It's not a tough change, just something I must have meant to do and then forgot about.

change SiteTitle in /theme/themesettings.yml

I'm curious about this one - the themesettings.yml should be overridable from your local settings file (or by settings defined via the bootstrapper). Does adding something like the following to your bootstrapper do the trick?

.AddSettings(new Dictionary<string, object>
    {
        { "SiteTitle", "My Site Title" },
// ...

If so, then this problem looks like a documentation thing and I should clarify that the theme settings should be defined in settings external to the theme to override the defaults (as opposed to editing the theme itself). Themes are intended to be used as-is so that theme updates are easier without having to do a bunch of diffs and conflict resolution.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Statiq

`Statiq.Docs` run exception caused by Docable theme compilation error #150

Uh oh!

{{title}}

Uh oh!

Replies: 2 comments 1 reply

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Statiq

Statiq.Docs run exception caused by Docable theme compilation error #150

Uh oh!

BryanWilhite Jun 26, 2022

Replies: 2 comments · 1 reply

Uh oh!

daveaglick Jun 27, 2022 Maintainer

Uh oh!

BryanWilhite Jul 3, 2022 Author

Statiq.Docs: a tour of what works

Uh oh!

daveaglick Jul 7, 2022 Maintainer

`Statiq.Docs` run exception caused by Docable theme compilation error #150

BryanWilhite
Jun 26, 2022

Replies: 2 comments 1 reply

daveaglick
Jun 27, 2022
Maintainer

BryanWilhite
Jul 3, 2022
Author

`Statiq.Docs`: a tour of what works

daveaglick Jul 7, 2022
Maintainer