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.

Sign up for GitHub

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

Jump to bottom

Exceptions when attempting to generate documentation #784

Closed
davedawkins opened this issue Jan 7, 2023 · 4 comments
Closed

Exceptions when attempting to generate documentation #784

davedawkins opened this issue Jan 7, 2023 · 4 comments

Comments

@davedawkins
Copy link
Contributor 

% 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

  • dotnet fsdocs build
  • programmatic approach (with 17.0.2)
  • programmatic approach (with 16.1.1)
  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>[email protected](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 [email protected](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>[email protected](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
Copy link
Contributor Author

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
Copy link
Collaborator

nojaf commented Jan 9, 2023

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 #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
Copy link
Collaborator

baronfel commented Jan 9, 2023

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

@davedawkins
Copy link
Contributor Author

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. 🙏

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
3 participants
@davedawkins @baronfel @nojaf