search

fsprojects / Fleece

Json mapper for F#
http://fsprojects.github.io/Fleece
Apache License 2.0
199 stars 31 forks source link

Proposal/Quesion: add `paket` to docs, use fsx paket extension #98

Open Gastove opened 3 years ago

Gastove commented 3 years ago

So, context: I've been trying to help get the build passing on Linux so I can help with documentation updates. In doing this, I've noticed: there are ergonomics challenges with requiring local-path release DLLs at the top of the script -- like this, taken from codec.fsx:

#r @"../../src/Fleece.SystemJson/bin/Release/netstandard2.1/System.Json.dll"
#r @"../../src/Fleece.SystemJson/bin/Release/netstandard2.1/Fleece.SystemJson.dll"
#r @"../../src/Fleece.SystemJson/bin/Release/netstandard2.1/FSharpPlus.dll"

The challenge here is, any change to the target framework for a library requires updating all the doc scripts, and the scripts themselves can't be loaded by an IDE until a release build is run. This is not insurmountable. And, I haven't actually worked with the F# doc system in use here before; this might be for the best!

This all said: I'd like to suggest the docs instead pull deps from Nuget using the paket, more like:

#r "paket:
nuget System.Json 4.7.1
nuget Fleece.SystemJson 0.9.0
nuget FsharpPlus"

Versions could be pinned or not (I'd have to confirm behaviour, but I assume absent a pin, latest is pulled, which seems reasonable to me).

Thoughs?

wallymathieu commented 3 years ago

You could use the F#5 functionality as well since this isn't sufficient complexity to warrant paket.

Gastove commented 3 years ago

Oh dang! I had no idea there was a paket-less way; that's a much better idea. Thank you!

So, I guess let's amend this proposal to "use published packages in doc scripts instead of locally built ones."

On Fri, Jan 22, 2021 at 5:12 AM Oskar Gewalli notifications@github.com wrote:

You could use the F#5 functionality as well since this isn't sufficient complexity to warrant paket.

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/fsprojects/Fleece/issues/98#issuecomment-765386844, or unsubscribe https://github.com/notifications/unsubscribe-auth/AA5F2JUB2NKJL6WDPUYLSUDS3F2STANCNFSM4WGQ3IBQ .

Gastove commented 3 years ago

Hrm. This will require updating the SDK version in the project global.json to a 5.x release, I think -- unless there's a different or better way to specify F# 5 for the docs. Thoughts?

wallymathieu commented 3 years ago

I think it would make sense to change to .net 5 in order to be able to improve the docs.