Building Documentation throws UnresolvedPathReferenceNoRange

[neoeinstein]

While in the process of preparing a possible new module for a pull request, I went to build the documentation using the GenerateDocs target in the build, but it failed while trying to format the metadata for FakeLib.dll. It appears to have been looking for the ICSharpCode.SharpZipLib assembly, but, not finding it, choked.

C:\dev\neoeinstein\FAKE\packages\FSharp.Formatting.CommandTool\tools\fsformatting.exe "metadataformat" "--generate" "--outdir" "./docs/apidocs/" "--layoutroots" "./help/templates/" "./help/templates/reference/" "--sourceRepo" "https://github.com/fsharp/FAKE/blob/master" "--sourceFolder" "C:\dev\neoeinstein\FAKE" "--parameters" "page-description" "FAKE - F# Make" "page-author" "Steffen Forkmann, Mauricio Scheffer, Colin Bull" "project-author" "Steffen Forkmann, Mauricio Scheffer, Colin Bull" "github-link" "https://github.com/fsharp/FAKE" "project-github" "http://github.com/fsharp/fake" "project-nuget" "https://www.nuget.org/packages/FAKE" "root" "http://fsharp.github.io/FAKE" "project-name" "FAKE - F# Make" --dllfiles "C:\dev\neoeinstein\FAKE\build\FakeLib.dll"
[0 sec] Resolving assembly: FSharp.Compiler.Service.resources, Version=0.0.82.0, Culture=en-US, PublicKeyToken=null
[0 sec] Resolving assembly: FSharp.Compiler.Service.resources, Version=0.0.82.0, Culture=en-US, PublicKeyToken=null
[0 sec] Resolving assembly: FSharp.Compiler.Service.resources, Version=0.0.82.0, Culture=en, PublicKeyToken=null
[0 sec] Resolving assembly: FSharp.Compiler.Service.resources, Version=0.0.82.0, Culture=en, PublicKeyToken=null
[3 sec] Reading assembly: C:\dev\neoeinstein\FAKE\build\FakeLib.dll
[3 sec] Parsing assembly (with documentation file 'C:\dev\neoeinstein\FAKE\build\FakeLib.XML')
[3 sec] Error while building member-name for Fake.AdditionalSyntax.( ? ) because: not a named type
[3 sec] Error while building member-name for Fake.AdditionalSyntax.( ?<- ) because: not a named type
[3 sec] Warning: Could not find documentation for 'T:Microsoft.FSharp.Core.obj'! (You can ignore this message when you have not written documentation for this member)
[3 sec] Warning: Could not find documentation for 'T:Microsoft.FSharp.Core.obj'! (You can ignore this message when you have not written documentation for this member)
[3 sec] Warning: Could not find documentation for 'T:Fake.AppVeyor.TestResultsType.MsTest'! (You can ignore this message when you have not written documentation for this member)

[3 sec] Warning: Could not find documentation for 'T:Fake.AppVeyor.TestResultsType.NUnit'! (You can ignore this message when you have not written documentation for this member) [3 sec] Warning: Could not find documentation for 'T:Fake.AppVeyor.TestResultsType.Xunit'! (You can ignore this message when you have not written documentation for this member)
[0 sec] received exception in MetadataFormat.Generate:
 UnresolvedPathReferenceNoRange
  ("ICSharpCode.SharpZipLib","ICSharpCode.SharpZipLib.BZip2.BZip2OutputStream")
Running build failed.
Error:
System.Exception: FSharp.Formatting "metadataformat" "--generate" "--outdir" "./docs/apidocs/" "--layoutroots" "./help/templates/" "./help/templates/reference/" "--sourceRepo" "https://github.com/fsharp/FAKE/blob/master" "--sourceFolder" "C:\dev\neoeinstein\FAKE" "--parameters" "page-description" "FAKE - F# Make" "page-author" "Steffen Forkmann, Mauricio Scheffer, Colin Bull" "project-author" "Steffen Forkmann, Mauricio Scheffer, Colin Bull" "github-link" "https://github.com/fsharp/FAKE" "project-github" "http://github.com/fsharp/fake" "project-nuget" "https://www.nuget.org/packages/FAKE" "root" "http://fsharp.github.io/FAKE" "project-name" "FAKE - F# Make" --dllfiles "C:\dev\neoeinstein\FAKE\build\FakeLib.dll" failed.
   at [email protected](String message) in C:\code\fake\src\app\FakeLib\FSharpFormattingHelper.fs:line 13
   at Fake.FSharpFormatting.run(String command) in C:\code\fake\src\app\FakeLib\FSharpFormattingHelper.fs:line 13
   at Fake.FSharpFormatting.CreateDocsForDlls(String outputDir, String templatesDir, IEnumerable`1 projectParameters, String sourceRepo, IEnumerable`1 dllFiles) in C:\code\fake\src\app\FakeLib\FSharpFormattingHelper.fs:line 44
   at [email protected](Unit _arg4) in C:\dev\neoeinstein\FAKE\build.fsx:line 120
   at Fake.TargetHelper.runSingleTarget(TargetTemplate`1 target) in C:\code\fake\src\app\FakeLib\TargetHelper.fs:line 411

Link to the commit that I have in progress that is causing the doc generation to fail: neoeinstein/FAKE@4d8054d

[neoeinstein]

Commit neoeinstein/FAKE@cf53c28 is a possible way to resolve this. It feels a bit contrived, as I am piggy-backing on the replacements tuple list in order to "backdoor" the libDir parameter in.

I don't want to change the signature of CreateDocsForDlls, as that would break clients, but I'm not sure if it needs to be broken out into its own separate task definition in the FSharpFormattingHelper. If that's what needs to be done, this becomes a two-step process since the FAKE build will depend on that new task being in the distributed FakeLib.dll before we can consume it.

Thoughts?

[forki]

/cc @tpetricek do you think the change in cf53c28 is needed/good?

[tpetricek]

Yes, adding libDirs sounds like a reasonable thing to do. In general, the recent versions of F# Formatting (after it started using F.C.S) require libDirs to be able to find all references... so if FakeLib.dll depends on something in lib folder, it should be listed there. (But if you copy the dependencies to the output build folder, then I'd prefer to add ./build to the libDirs)