fsdocs build fails while cracking projects that have dependencies on another projects

[ArtemyB]

Tried to use fsdocs (v11.2.0) to generates docs only for solution with multiple projects that has dependencies on each other. But the tool successfully generates API reference only for the project (in solution) that has no dependencies and fails on other projects which have references to other *.fsproj. Final Error log entry from fsdocs looks not very helpful:

log -
   at Microsoft.FSharp.Core.PrintfModule.PrintFormatToStringThenFail@1433.Invoke(String message) in D:\workspace\_work\1\s\src\fsharp\FSharp.Core\printf.fs:line 1433
   at FSharp.Formatting.CommandTool.Crack.projectInfos@319.Invoke(String p) in /home/runner/work/FSharp.Formatting/FSharp.Formatting/src/FSharp.Formatting.CommandTool/ProjectCracker.fs:line 321

I've created a simple demo solution which demonstrates the problem: https://github.com/ArtemyB/FsDocsSample. The solution consists of 2 .NET Standard library projects: the 1st one has no dependencies (fsdocs successfully generates API reference for it) and the 2nd has dependency on the 1st (fsdocs does not generate API reference for it).

Full fsdocs console output can bee viewed there: ArtemyB/FsDocsSample#1

I've also tested an earlier fsdocs version (v9.0.1) that doesn't use Ionide.ProjInfo for project cracking and it handles projects with dependencies successfully (however it fails on projects with third-party dependencies due to #616).

[jwosty]

Running into this problem, and can't use the downgrade workaround due to third party dependencies. Is there any solution to this?

Also worth noting that I can't update to the latest fsdocs tool because it requires dotnet 7 and I need to build my package for .net 6 since Fable doesn't support .net 7 yet. Getting a bit stuck here...

[nojaf]

Hello, you could try to pass in the missing reference as --fscoptions argument.
Example --fscoptions " -r:MyAssembly.dll" (mind the space after ", it is required to parse correctly).

We use this in Fantomas.
This works from 15.0.2 and higher.

Another option would be to start looking at Fable 4, it supports dotnet 7 these days. I've recently upgraded.

I hope this helps.

[github-actions]

🤖 This is an automated response from Repo Assist.

Checking in on this issue. The workaround @nojaf shared in January 2023 — passing the missing reference explicitly via --fscoptions " -r:path/to/MyAssembly.dll" — remains available in current versions.

A few notes that may help:

Ensure projects are built before running fsdocs build
fsdocs does not build your projects — it cracks them (reads MSBuild metadata) and then generates docs from the pre-built output assemblies. If project A hasn't been compiled when fsdocs cracks project B (which depends on A), the cracking step can fail. Running dotnet build on the whole solution first generally resolves this.

Build order from solution file
When running fsdocs build in a directory containing a .sln file, projects are processed in dependency order (project A before project B), which should help Ionide.ProjInfo resolve cross-project references correctly.

Is this still reproducible in v22?
The original report was with v11.2.0. The project cracking code has been substantially reworked since then. If anyone can confirm whether this still occurs with the current version (22.0.0-alpha.1) — particularly with the demo repo at https://github.com/ArtemyB/FsDocsSample — that would help prioritise a proper fix. If dotnet build + fsdocs build now works correctly, it might be worth closing this issue.

Generated by Repo Assist · ◷

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/repo-assist.md@346204513ecfa08b81566450d7d599556807389f

[dsyme]

thumbs up to reply