Enhance the "Explanation" section of the documentation

[64J0]

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.

[cartermp]

Love it!

[64J0]

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

[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

[64J0]

All right, thanks @cartermp 🚀

[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

[cartermp]

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.

[64J0]

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.

• https://github.com/SaturnFramework/Saturn/actions/runs/3032621248/jobs/4880300795

[baronfel]

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.

[cartermp]

Oh yeah, this is me fucking around with github actions

[64J0]

I'm taking a look at this command and noticed some interesting points:

1. Most of the errors I got running locally were related to the file docs/generators/apiref.fsx;
2. I was able to fix some of them by updating the path for dll files in the beginning of the script. FSharp.Formatting is creating a folder named 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.

[64J0]

Great, the last import remaining was renamed. Found the information here:

• https://github.com/fsprojects/FSharp.Formatting/blob/d0ac84e3a39221cc536d34a57e3f0f9dfec0f2df/RELEASE_NOTES.md

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"

[64J0]

PR: #357