CSharp library not used for generating API docs

[kMutagene]

At some point the fsdocs tool stopped generating API docs for a C# library (Plotly.NET.CSharp) in a mixed F#/C# solution (https://github.com/plotly/Plotly.NET/tree/dev/src). I am 100% certain that this worked in the past. Now the tool only selects the F# projects for API doc generation:

./> "dotnet.exe"  fsdocs watch --eval --clean --properties Configuration=Release --parameters fsdocs-package-version 5.0.0 (In: false, Out: false, Err: false)
discarding project state in '.fsdocs/cache' as now invalid
cracking projects...
  skipping project 'build.fsproj' because it isn't a library

Inputs for API Docs:
    C:\Users\schne\source\repos\plotly\Plotly.NET\src\Plotly.NET\bin\Release\netstandard2.0\Plotly.NET.dll
    C:\Users\schne\source\repos\plotly\Plotly.NET\src\Plotly.NET.ImageExport\bin\Release\netstandard2.0\Plotly.NET.ImageExport.dll
    C:\Users\schne\source\repos\plotly\Plotly.NET\src\Plotly.NET.Interactive\bin\Release\netstandard2.1\Plotly.NET.Interactive.dll

Substitutions/parameters:
  root --> http://localhost:8901/
  fsdocs-authors --> Timo Mühlhaus, Kevin Schneider, F# open source contributors
  fsdocs-collection-name --> Plotly.NET

...

I have a build step that builds all projects including the C# project before starting docs generation, so the binaries are there.

Could it be a problem that the C# project targets .net6.0 ?

[nojaf]

Hi there, does it get picked up when you specify it explicitly via --projects?

The help text says Project files to build API docs for outputs, defaults to all packable projects..
Just checking, but is it packable?

[kMutagene]

Just checking, but is it packable?

Does this have to be set explicitly? I do not set anything in that regard on the F# projects. i am publishing all libraries (including the C# library) as nuget packages via dotnet pack so i would expect it to be packable right?

does it get picked up when you specify it explicitly via --projects?

I have not tried it now, but remember it not working when i tried last time. Will try it again later and report back

--projects | Project files to build API docs for outputs, defaults to all packable projects

How are multiple projects expected to be passed here? comma-separated full paths? one directory containing all projects?

[nojaf]

How are multiple projects expected to be passed here?

Hmm, I'm not quite sure, you could try:

• --projects A.fsproj B.csproj
• --projects A.fsproj --projects B.csproj

I don't think it will be comma-separated, it really will depend on how https://github.com/commandlineparser/commandline does the argument parsing.

full paths?

Yeah, definitely try full paths when relative ones don't work.

one directory containing all projects?

No, it does expect actual projects, not directories.

[kMutagene]

So this is really weird. If i run this fake build task:

let watchDocs =
    BuildTask.create "WatchDocs" [ build ] {
        printfn "watching docs with stable version %s" stableDocsVersionTag

        runDotNet
            "fsdocs watch --eval --clean --properties Configuration=Release --projects <absolute project paths here>
            "./"
    }

which basically only runs

dotnet fsdocs watch --eval --clean --properties Configuration=Release --projects <absolute project paths here>

i get this error (for ALL, F# and C#) projects:

skipping project 'Plotly.NET.fsproj' because an error occurred while cracking it: System.Exception: project 'C:\Users\epos\plotly\Plotly.NET\src\Plotly.NET\Plotly.NET.fsproj' not restored
   at Microsoft.FSharp.Core.PrintfModule.PrintFormatToStringThenFail@1448.Invoke(String message)
   at fsdocs.Crack.crackProjectFile[a](a slnDir, FSharpList`1 extraMsbuildProperties, String file) in /home/runner/work/FSharp.Formatting/FSharp.Formatting/src/fsdocs-tool/ProjectCracker.fs:line 346
   at fsdocs.Crack.projectInfos@451.Invoke(String p) in /home/runner/work/FSharp.Formatting/FSharp.Formatting/src/fsdocs-tool/ProjectCracker.fs:line 453
skipping project 'Plotly.NET.CSharp.csproj' because an error occurred while cracking it: System.Exception: project 'C:epos\plotly\Plotly.NET\src\Plotly.NET.CSharp\Plotly.NET.CSharp.csproj' not restored
   at Microsoft.FSharp.Core.PrintfModule.PrintFormatToStringThenFail@1448.Invoke(String message)
   at fsdocs.Crack.crackProjectFile[a](a slnDir, FSharpList`1 extraMsbuildProperties, String file) in /home/runner/work/FSharp.Formatting/FSharp.Formatting/src/fsdocs-tool/ProjectCracker.fs:line 346
   at fsdocs.Crack.projectInfos@451.Invoke(String p) in /home/runner/work/FSharp.Formatting/FSharp.Formatting/src/fsdocs-tool/ProjectCracker.fs:line 453

if i run the same command from the command line, everything works out.

[nojaf]

Euhm, yeah this is some fun stuff. Project cracking fails and who knows what FAKE is doing to influence it.
What OS and dotnet SDK version are you using?

[kMutagene]

What OS and dotnet SDK version are you using?

Win 11 Pro Version 10.0.22621 Build 22621
and .NET 6.0.416

But it seems like the workaround of just building with fake and then calling the tool manually with --projects will work for me for now. as you said, diagnosing what fake is actually influencing here might be quite hard (and even a local problem maybe?)

[nojaf]

If you were running with the dotnet 8 preview SDK I had some environment variables in mind you could give a try. But as you are sticking to the stable 6 SDK I have no immediate idea what you could try.

I would work around it for now. But we should keep this ticket open and provide a better DX when project cracking fails.

[github-actions]

🤖 This is an automated response from Repo Assist.

Looking at the code in ProjectCracker.fs, there are two things that could cause a C# project to be silently excluded from API doc generation:

1. (GenerateDocumentationFile) not set (most likely)

fsdocs requires each project to have (GenerateDocumentationFile)true(/GenerateDocumentationFile) set in the project file (or in Directory.Build.props). Without it, the project is skipped with the message:

skipping project 'Plotly.NET.CSharp.csproj' because it doesn't have (GenerateDocumentationFile)

F# projects in the solution likely have this set already (perhaps via Directory.Build.props), but C# projects often don't get it by default. Adding this to Plotly.NET.CSharp.csproj should allow the project to be picked up:

(PropertyGroup)
  (GenerateDocumentationFile)true(/GenerateDocumentationFile)
(/PropertyGroup)

2. Auto-discovery only finds .fsproj files (if no .sln is present)

When no .sln file is found, fsdocs's auto-discovery only enumerates *.fsproj files — it does not look for *.csproj. If a .sln file is present (which it is for Plotly.NET), the C# project would be discovered through the solution, so this is probably not the issue here.

If adding GenerateDocumentationFile doesn't resolve it, using --projects explicitly with both the .fsproj and .csproj paths should work as a reliable fallback.

Generated by Repo Assist

To install this workflow, run gh aw add githubnext/agentics/workflows/repo-assist.md@ee50a3b7d1d3eb4a8c409ac9409fd61c9a66b0f5. View source at https://github.com/githubnext/agentics/tree/ee50a3b7d1d3eb4a8c409ac9409fd61c9a66b0f5/workflows/repo-assist.md.

[dsyme]

Given it's an old issue let's run with that answer