search

fsprojects / FSharp.Formatting

F# tools for generating documentation (Markdown processor and F# code formatter)
https://fsprojects.github.io/FSharp.Formatting/
Other
462 stars 155 forks source link

Exceptions when attempting to generate documentation #784

Closed davedawkins closed 1 year ago

davedawkins commented 1 year ago 
% dotnet --version
6.0.404
% uname -a
Darwin davebook.local 22.1.0 Darwin Kernel Version 22.1.0: Sun Oct  9 20:14:54 PDT 2022; root:xnu-8792.41.9~2/RELEASE_X86_64 x86_64

Have tried using

  1. fsdocs 
david@davebook Sutil % dotnet fsdocs build                       
getting projects from solution file /Users/david/projects/Sutil/Sutil.sln
Unhandled exception. System.Exception: cannot load the sln
 ---> Ionide.ProjInfo.Sln.Exceptions.InvalidProjectFileException: SolutionParseNestedProjectUndefinedError  /Users/david/projects/Sutil/Sutil.sln
   at Ionide.ProjInfo.Sln.Shared.ProjectFileErrorUtilities.VerifyThrowInvalidProjectFile(Boolean condition, String errorSubCategoryResourceName, BuildEventFileInfo projectFile, Exception innerException, String resourceName, Object[] args) in D:\a\proj-info\proj-info\src\Ionide.ProjInfo.Sln\vendor\ProjectFileErrorUtilities.cs:line 150
   at Ionide.ProjInfo.Sln.Shared.ProjectFileErrorUtilities.VerifyThrowInvalidProjectFile(Boolean condition, String errorSubCategoryResourceName, BuildEventFileInfo projectFile, String resourceName, Object[] args) in D:\a\proj-info\proj-info\src\Ionide.ProjInfo.Sln\vendor\ProjectFileErrorUtilities.cs:line 101
   at Ionide.ProjInfo.Sln.Construction.SolutionFile.ParseNestedProjects() in D:\a\proj-info\proj-info\src\Ionide.ProjInfo.Sln\vendor\SolutionFile.cs:line 1370
   at Ionide.ProjInfo.Sln.Construction.SolutionFile.ParseSolution() in D:\a\proj-info\proj-info\src\Ionide.ProjInfo.Sln\vendor\SolutionFile.cs:line 564
   at Ionide.ProjInfo.Sln.Construction.SolutionFile.ParseSolutionFile() in D:\a\proj-info\proj-info\src\Ionide.ProjInfo.Sln\vendor\SolutionFile.cs:line 514
   at Ionide.ProjInfo.Sln.Construction.SolutionFile.Parse(String solutionFile) in D:\a\proj-info\proj-info\src\Ionide.ProjInfo.Sln\vendor\SolutionFile.cs:line 328
   at Ionide.ProjInfo.InspectSln.tryParseSln(String slnFilePath) in D:\a\proj-info\proj-info\src\Ionide.ProjInfo\InspectSln.fs:line 81
   --- End of inner exception stack trace ---
   at fsdocs.Crack.getProjectsFromSlnFile(String slnPath) in /home/runner/work/FSharp.Formatting/FSharp.Formatting/src/fsdocs-tool/ProjectCracker.fs:line 304
   at fsdocs.Crack.crackProjects(Boolean strict, FSharpList`1 extraMsbuildProperties, FSharpOption`1 userRoot, FSharpOption`1 userCollectionName, FSharpList`1 userParameters, FSharpList`1 projects, Boolean ignoreProjects) in /home/runner/work/FSharp.Formatting/FSharp.Formatting/src/fsdocs-tool/ProjectCracker.fs:line 328
   at <StartupCode$fsdocs>.$BuildCommand.Execute@808-2.Invoke(Unit unitVar0) in /home/runner/work/FSharp.Formatting/FSharp.Formatting/src/fsdocs-tool/BuildCommand.fs:line 820
   at fsdocs.Utils.cacheBinary[T](String cacheFile, FSharpFunc`2 cacheValid, FSharpFunc`2 f) in /home/runner/work/FSharp.Formatting/FSharp.Formatting/src/fsdocs-tool/ProjectCracker.fs:line 68
   at fsdocs.CoreBuildOptions.Execute() in /home/runner/work/FSharp.Formatting/FSharp.Formatting/src/fsdocs-tool/BuildCommand.fs:line 805
   at fsdocs.Main.main@15.Invoke(BuildCommand opts) in /home/runner/work/FSharp.Formatting/FSharp.Formatting/src/fsdocs-tool/Program.fs:line 15
   at CommandLine.ParserResultExtensions.MapResult[T1,T2,TResult](ParserResult`1 result, Func`2 parsedFunc1, Func`2 parsedFunc2, Func`2 notParsedFunc)
   at fsdocs.Main.main(String[] argv) in /home/runner/work/FSharp.Formatting/FSharp.Formatting/src/fsdocs-tool/Program.fs:line 10
  1. Programmatic approach (using 16.1.1)
david@davebook Sutil % dotnet fsi gendoc.fsx                     
  loading 1 assemblies...
isNetCoreApp = true
  registering entities for assembly Sutil...
FSharp.Compiler.DiagnosticsLogger+UnresolvedPathReferenceNoRange: Assembly: Fable.Core, full path: Fable.Core.JS.Promise`1
   at FSharp.Compiler.TypedTree.CcuThunk.EnsureDerefable(String[] requiringPath) in D:\a\_work\1\s\src\Compiler\TypedTree\TypedTree.fs:line 5394
   at FSharp.Compiler.TypedTree.NonLocalEntityRef.TryDeref(Boolean canError) in D:\a\_work\1\s\src\Compiler\TypedTree\TypedTree.fs:line 3263
   at FSharp.Compiler.TypedTree.EntityRef.get_Deref() in D:\a\_work\1\s\src\Compiler\TypedTree\TypedTree.fs:line 3358
   at FSharp.Compiler.TypedTreeOps.stripTyEqnsA(TcGlobals g, Boolean canShortcut, TType ty) in D:\a\_work\1\s\src\Compiler\TypedTree\TypedTreeOps.fs:line 747
   at FSharp.Compiler.TypedTreeOps.isUnitTy(TcGlobals g, TType ty) in D:\a\_work\1\s\src\Compiler\TypedTree\TypedTreeOps.fs:line 1812
   at FSharp.Compiler.TypedTreeOps.GetTopValTypeInCompiledForm(TcGlobals g, ValReprInfo topValInfo, Int32 numEnclosingTypars, TType ty, Range m) in D:\a\_work\1\s\src\Compiler\TypedTree\TypedTreeOps.fs:line 2528
   at FSharp.Compiler.TypedTreeOps.XmlDocSigOfVal(TcGlobals g, Boolean full, String path, Val v) in D:\a\_work\1\s\src\Compiler\TypedTree\TypedTreeOps.fs:line 8662
   at FSharp.Compiler.InfoReader.GetXmlDocSigOfScopedValRef(TcGlobals g, EntityRef tcref, ValRef vref) in D:\a\_work\1\s\src\Compiler\Checking\InfoReader.fs:line 1039
   at FSharp.Compiler.Symbols.FSharpMemberOrFunctionOrValue.get_XmlDocSig() in D:\a\_work\1\s\src\Compiler\Symbols\Symbols.fs:line 1996
   at FSharp.Formatting.ApiDocs.CrossReferences.getXmlDocSigForMember(FSharpMemberOrFunctionOrValue memb) in /home/runner/work/FSharp.Formatting/FSharp.Formatting/src/FSharp.Formatting.ApiDocs/GenerateModel.fs:line 712
   at FSharp.Formatting.ApiDocs.CrossReferenceResolver.registerMember(FSharpMemberOrFunctionOrValue memb) in /home/runner/work/FSharp.Formatting/FSharp.Formatting/src/FSharp.Formatting.ApiDocs/GenerateModel.fs:line 806
   at FSharp.Formatting.ApiDocs.CrossReferenceResolver.registerEntity(FSharpEntity entity) in /home/runner/work/FSharp.Formatting/FSharp.Formatting/src/FSharp.Formatting.ApiDocs/GenerateModel.fs:line 836
   at <StartupCode$FSharp-Formatting-ApiDocs>.$GenerateModel.assemblies@2927.Invoke(FSharpEntity arg00)
   at Microsoft.FSharp.Collections.SeqModule.Iterate[T](FSharpFunc`2 action, IEnumerable`1 source) in D:\a\_work\1\s\src\FSharp.Core\seq.fs:line 597
   at FSharp.Formatting.ApiDocs.ApiDocModel.Generate(FSharpList`1 projects, String collectionName, FSharpOption`1 libDirs, FSharpOption`1 otherFlags, Boolean qualify, FSharpOption`1 urlRangeHighlight, String root, FSharpList`1 substitutions, FSharpFunc`2 onError, ApiDocFileExtensions extensions) in /home/runner/work/FSharp.Formatting/FSharp.Formatting/src/FSharp.Formatting.ApiDocs/GenerateModel.fs:line 2927
   at FSharp.Formatting.ApiDocs.ApiDocs.GenerateHtml(FSharpList`1 inputs, String output, String collectionName, FSharpList`1 substitutions, FSharpOption`1 template, FSharpOption`1 root, FSharpOption`1 qualify, FSharpOption`1 libDirs, FSharpOption`1 otherFlags, FSharpOption`1 urlRangeHighlight, FSharpOption`1 onError) in /home/runner/work/FSharp.Formatting/FSharp.Formatting/src/FSharp.Formatting.ApiDocs/ApiDocs.fs:line 153
   at <StartupCode$FSI_0002>.$FSI_0002.main@() in /Users/david/projects/Sutil/gendoc.fsx:line 10
Stopped due to error
david@davebook Sutil %
  1. Programmatic approach (using 17.*)
david@davebook Sutil % dotnet fsi gendoc.fsx

error FS0193: Could not load file or assembly 'FSharp.Compiler.Service, Version=42.7.101.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a'.

System.IO.FileNotFoundException: Could not load file or assembly 'FSharp.Compiler.Service, Version=42.7.101.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a'. The system cannot find the file specified.

File name: 'FSharp.Compiler.Service, Version=42.7.101.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a'
   at FSharp.Formatting.ApiDocs.ApiDocModel.Generate(FSharpList`1 projects, String collectionName, FSharpOption`1 libDirs, FSharpOption`1 otherFlags, Boolean qualify, FSharpOption`1 urlRangeHighlight, String root, FSharpList`1 substitutions, FSharpFunc`2 onError, ApiDocFileExtensions extensions)
   at FSharp.Formatting.ApiDocs.ApiDocs.GenerateHtml(FSharpList`1 inputs, String output, String collectionName, FSharpList`1 substitutions, FSharpOption`1 template, FSharpOption`1 root, FSharpOption`1 qualify, FSharpOption`1 libDirs, FSharpOption`1 otherFlags, FSharpOption`1 urlRangeHighlight, FSharpOption`1 onError) in /home/runner/work/FSharp.Formatting/FSharp.Formatting/src/FSharp.Formatting.ApiDocs/ApiDocs.fs:line 153
   at <StartupCode$FSI_0002>.$FSI_0002.main@() in /Users/david/projects/Sutil/gendoc.fsx:line 10
Stopped due to error

My gendoc.fsx script:

#r "nuget: FSharp.Formatting,17.2.0"
//#r "nuget: FSharp.Formatting,16.1.1"

open FSharp.Formatting.ApiDocs
open System.IO

let file = "./src/Sutil/bin/Release/netstandard2.0/Sutil.dll"

let input = ApiDocInput.FromFile(file)

ApiDocs.GenerateHtml(
    [ input ],
    output = "./apidocs/output",
    collectionName = "Sutil",
    template = Path.Combine("apidocs", "templates", "template.html"),
    substitutions = []
)

What am I doing wrong? Feel free to check out and build Sutil

% git clone -s https://github.com/davedawkins/Sutil
% dotnet tool restore
% npm install
% dotnet build -c Release src/Sutil/Sutil.fsproj
davedawkins commented 1 year ago

I got Visual Studio to rebuild the solution file (removed the Sutil main project and re-added it). I may be able to diff and report back

nojaf commented 1 year ago

Hello, when using 6.0.404 I'm not sure you can use the 17.x version. 17 has a dependency on FCS 42.7.101 which takes a dependency on MSBuild 17.4 packages. So the MSBuild you bring in is more recent than the one your SDK uses. I'm not 100% sure that is the problem you have but that seems likely.

When going with 16.1.1 and 6.0.404 I think the MSBuild libraries will resolve fine. There your script is trying to generate API docs for a netstandard. Building Sutil won't output any referenced DLLs as a console app would do. To generate the documentation you do need to resolve any additional missing references. (Looks like https://github.com/fsprojects/FSharp.Formatting/issues/680)

I cloned your repo, and create a console app that references Sutil. Build that project and added the missing references:

#r "nuget: FSharp.Formatting, 16.1.1"

open FSharp.Formatting.ApiDocs
open System.IO

let file = "./Entry/bin/Release/net6.0/Sutil.dll"

let input = ApiDocInput.FromFile(file)

let references = 
    [
        "Browser.Blob.dll"
        "Browser.Css.dll"
        "Browser.Dom.dll"
        "Browser.Event.dll"
        "Browser.Gamepad.dll"
        "er.MediaQueryList.dll"
        "Browser.Svg.dll"
        "Browser.WebStorage.dll"
        "ConstructStyleSheetsPolyfill.dll"
        "Fable.Core.dll"
        "Fable.Promise.dll"
        "Feliz.Engine.Bulma.dll"
        "Feliz.Engine.dll"
        "Feliz.Engine.Event.dll"
        "FSharp.Core.dll"
    ]
    |> List.map (fun dep ->
        Path.Combine(__SOURCE_DIRECTORY__, "Entry/bin/Release/net6.0", dep)
        |> sprintf "-r:%s")

ApiDocs.GenerateHtml(
    [ input ],
    output = "./apidocs/output",
    collectionName = "Sutil",
    // template = Path.Combine("apidocs", "templates", "template.html"),
    substitutions = [],
    otherFlags = references
)

This was generating documentation for me.

@baronfel FCS has a preview version on NuGet without any deps to MSBuild. Do we want to upgrade to that?

baronfel commented 1 year ago

I'd like to get @kevinransom to push a stable version, but yeah that should be the path forward.

davedawkins commented 1 year ago

Thank you everyone for taking a look - I closed it because I found I was suffering from a mixture of dotnet version, fsdocs version and corrupted solution file. @nojaf You worked hard on that, thank you, that's amazing. 🙏