Closed 64J0 closed 1 year ago
I saw that the project documentation is not update yet when I visit the URL https://saturnframework.org/
. What is it lacking to be updated? @cartermp
Oh, blegh, it looks like docs changes don't get updated upon merge to the main branch. I'll see if I can adjust that
All right, thanks @cartermp 🚀
Ugh, okay, so there's probably an issue with using a very old version of Fornax here, so the docs aren't actually getting built and run anymore. Will investigate
Quick update - there's something that's a little fundamentally fucky going on here, likely related to the docs gen engine just being old. I've looked at it a bit but haven't spent hours on it yet.
Ack, I noticed that there is something weird with the .NET setup in the Github Actions environment. It failed to find the SDK version that you tried 5.0.17
.
5.0.17 is a runtime version, not an SDK version - if you use a version like 5.0.x
instead that should do what you want.
Oh yeah, this is me fucking around with github actions
I'm taking a look at this command and noticed some interesting points:
docs/generators/apiref.fsx
;netstandard2.1
instead of netstandard2.0
, and the name of the files inside it changed as well.Now I'm only getting an error for the FSharp.MetadataFormat.dll
, when running dotnet fornax build
inside the docs/
folder.
Logs:
❯ dotnet fornax build
Load Errors: [|~/company/codes/foss/Saturn/docs/generators/apiref.fsx (6,1)-(6,88) parameter error Unable to find the file '../../packages/docs/FSharp.Formatting/lib/netstandard2.0/FSharp.MetadataFormat.dll' in any of
~/dotnet/shared/Microsoft.NETCore.App/6.0.2
~/dotnet/packs/Microsoft.NETCore.App.Ref/6.0.2/ref/net6.0
~/company/codes/foss/Saturn/docs
~/.nuget/packages/fornax/0.14.0/tools/net5.0/any/|]
Open Errors: [|input.fsx (1,6)-(1,12) typecheck error The namespace or module 'Apiref' is not defined.|]
Get generator Errors: [|input.fsx (1,16)-(1,24) typecheck error The value or constructor 'generate' is not defined. Maybe you want one of the following:
Generating
GenerationPhase
GeneratorConfig
GeneratorOutput
GeneratorTrigger|]
[15:53:13] multiple files generation failed
The update I applied to solve some of the errors:
// docs/generators/apiref.fsx
#r "../../packages/docs/FSharp.Formatting/lib/netstandard2.1/FSharp.Formatting.CodeFormat.dll"
#r "../../packages/docs/FSharp.Formatting/lib/netstandard2.1/FSharp.Formatting.Markdown.dll"
#r "../../packages/docs/FSharp.Formatting/lib/netstandard2.1/FSharp.Formatting.Literate.dll"
I'll keep investigating this, but apparently this MetadataFormat.dll
does not exist anymore.
Great, the last import remaining was renamed. Found the information here:
FSharp.MetadataFormat --> FSharp.Formatting.ApiDocs
So the imports must be:
// docs/generators/apiref.fsx
#r "../../packages/docs/FSharp.Formatting/lib/netstandard2.1/FSharp.Formatting.CodeFormat.dll"
#r "../../packages/docs/FSharp.Formatting/lib/netstandard2.1/FSharp.Formatting.Markdown.dll"
#r "../../packages/docs/FSharp.Formatting/lib/netstandard2.1/FSharp.Formatting.Literate.dll"
#r "../../packages/docs/FSharp.Formatting/lib/netstandard2.1/FSharp.Formatting.ApiDocs.dll"
Description:
With this PR I'm enhancing the pages of the "Explanation" section of the documentation.
The scope of changes is relatively small. Most of the time I'm simply adding "," or ".", or breaking paragraphs to make it easier to read. On other pages, I merely added references to some documentation that will help new people learn this tool and F#.
Let me know if there's something you'd like me to change.