build GenerateReferenceDocs succeeds, but produces no output

[ReedCopsey]

I've been trying to update my project to use the latest ProjectScaffold, but even with a brand new copy (just download and build, on Windows, using VS2013 tools), build GenerateReferenceDocs succeeds, but generates no output.

The build step runs, and shows:

Finished Target: GenerateHelp
Starting Target: GenerateReferenceDocs (==> RunTests, GenerateHelp)
Building documentation (Default), this could take some time, please wait...
C:\Users\Reed\Documents\GitHub\ProjectScaffold-master\packages\build\FAKE\tools\FAKE.exe  --fsiargs -d:FAKE -d:RELEASE -d:REFERENCE "generate.fsx"
FSharp.Formatting Information: 0 : FSharp.Formatting Logging setup!
Yaaf.FSharp.Scriping Information: 0 : Yaaf.FSharp.Scripting Logging setup!
Copying file: C:\Users\Reed\Documents\GitHub\ProjectScaffold-master\docs\output\img\logo-template.pdn
Copying file: C:\Users\Reed\Documents\GitHub\ProjectScaffold-master\docs\output\img\logo.png
Copying styles and scripts: C:\Users\Reed\Documents\GitHub\ProjectScaffold-master\docs\output\content\style.css
Copying styles and scripts: C:\Users\Reed\Documents\GitHub\ProjectScaffold-master\docs\output\content\style_light.css
Copying styles and scripts: C:\Users\Reed\Documents\GitHub\ProjectScaffold-master\docs\output\content\tips.js
Copying styles and scripts: C:\Users\Reed\Documents\GitHub\ProjectScaffold-master\docs\output\content\img\github-blue.png
Copying styles and scripts: C:\Users\Reed\Documents\GitHub\ProjectScaffold-master\docs\output\content\img\github.png
Finished Target: GenerateReferenceDocs

But, as you can see from the above, nothing is put in the reference folder under output, and no reference docs are generated.

Again, this was just taking the current master, downloading as a zip, running build, then build GenerateReferenceDocs - with no changes or updates. The command "succeeds" but doesn't seem to actually generate the reference folder or documentation.

[ReedCopsey]

It also appears that ReferenceBinaries isn't set properly during the init phase - it's coming through as empty. However, setting it up manually doesn't seem to change the output.

[ReedCopsey]

After further investigating, it appears that the -d:REFERENCE flag isn't coming through into generate.fsx correctly. I'm not sure why, but when I change the end of generate.fsx to:

// Generate
copyFiles()

printfn "AFTER FILE COPY"

#if HELP
printfn "Calling buildDocumentation()"
buildDocumentation()
#endif
#if REFERENCE
printfn "Calling buildReference()"
buildReference()
#endif

printfn "AFTER DEFINES"

And then run, the main help generation succeeds (and prints as expected), but I then see:

Help generated
Finished Target: GenerateHelp
Starting Target: GenerateReferenceDocs (==> RunTests, GenerateHelp)
Building documentation (Default), this could take some time, please wait...
C:\Users\Reed\Documents\GitHub\Gjallarhorn\packages\build\FAKE\tools\FAKE.exe  --fsiargs -d:FAKE -d:RELEASE -d:REFERENCE "generate.fsx"
FSharp.Formatting Information: 0 : FSharp.Formatting Logging setup!
Yaaf.FSharp.Scriping Information: 0 : Yaaf.FSharp.Scripting Logging setup!
Copying file: [myproj]\docs\output\img\logo-template.pdn
Copying file: [myproj]\docs\output\img\logo.png
Copying file: [myproj]\docs\output\img\Thumbs.db
Copying styles and scripts: [myproj]\docs\output\content\style.css
Copying styles and scripts: [myproj]\docs\output\content\style.css.bak
Copying styles and scripts: [myproj]\docs\output\content\style_light.css
Copying styles and scripts: [myproj]\docs\output\content\tips.js
Copying styles and scripts: [myproj]\docs\output\content\img\github-blue.png
Copying styles and scripts: [myproj]\docs\output\content\img\github.png
AFTER FILE COPY
Calling buildDocumentation()
AFTER DEFINES
Finished Target: GenerateReferenceDocs

Note that the FAKE.exe line reported (and I verified this) is being called with -d:REFERENCE, but within the generate.fsx, that is being bypassed. I'm not familiar with how FAKE passes arguments through to FSI, but it seems like there's a bug happening here...

(Again, this is using the standard build.fsx/generate.fsx, with the only "change" being running the setup once)

[forki]

Target "GenerateReferenceDocs" (fun _ ->
    if not <| executeFSIWithArgs "docs/tools" "generate.fsx" ["--define:RELEASE"; "--define:REFERENCE"] [] then
      failwith "generating reference documentation failed"
)

is a workaround until we know how to solve fsharp/fsharp-compiler-docs#511

[forki]

It was an issue with FAKE's script caching. fsiOptions need to invalidate the cache as well.

In order to fix your issue: "paket update nugate FAKE" should do the trick

cc @matthid

[matthid]

Thanks for the CC. I think this was one of the arguments for FAKE targets instead of compiler directives. I really think we should make the documentation generation a proper FAKE script with multiple targets.