Expand documentation #100

Gastove · 2021-01-23T20:04:00Z

Note: to get everything working nicely, this branch was opened off of my branch for #97. It will be much easier to review this PR after #97 has closed, as it contains all of 97s commits!

This PR proposes some expansions to Fleece's documentation. In particular, my goal is to cover sets of use-cases I found non-obvious as a newcomer to Fleece. I've tried to clarify a few points around working with DUs, as well as dealing with fields that are required in a given JSON object but not in F#.

Per #98, I've also bumped the SDK version in the project global.json to 5.0, to allow the use of F#5's package-loading features in documentation scripts.

I am not, for the record, adamant about any of this. Fleece is a great project, and I'd love to help! And, I'm pretty happy to take a different approach.

Gastove · 2021-01-23T23:36:06Z

Huh. I just realized I never bumped the actual dotnet versions being used for CI. But -- CI is perfectly happy, so it certainly doesn't seem to be harming anything. If the global.json change works for y'all, I'm very happy to make sure CI stays in sync as part of this PR. Just let me know!

wallymathieu · 2021-01-24T18:07:28Z

I think it makes sense to upgrade in order to be able to use this new feature 👍. I think you can also remove the:

docsrc/tool/download_nugets.ps1
docsrc/tool/download_nugets.sh

since these download needed nuget packages into folders, while if you use the new F# 5 nuget reference syntax these are unnecessary.

docsrc/content/codec.fsx

wallymathieu · 2021-01-24T18:14:03Z

Note for instance:

https://github.com/fsprojects/Fleece/blob/master/docsrc/tool/generate.fs#L52-L73

let docPackagePath  path =
    __SOURCE_DIRECTORY__ + @"/../../packages/docs/" + path
...
let evaluationOptions = 
    [| 
         includeDir "FSharp.Core/lib/netstandard2.0/"
         reference "FSharp.Core/lib/netstandard2.0/FSharp.Core.dll" 
         includeDir "FSharp.Literate/lib/netstandard2.0/" 
         includeDir "MathNet.Numerics/lib/netstandard2.0/" 
         reference "MathNet.Numerics/lib/netstandard2.0/MathNet.Numerics.dll" 
         includeDir "MathNet.Numerics.FSharp/lib/netstandard2.0/" 
         reference "MathNet.Numerics.FSharp/lib/netstandard2.0/MathNet.Numerics.FSharp.dll" 
         includeDir "System.Buffers/lib/netstandard2.0/" 
         includeDir "System.Collections.Immutable/lib/netstandard2.0/" 
         includeDir "System.Reflection.Metadata/lib/netstandard2.0/" 
         includeDir "System.ValueTuple/lib/netstandard1.0/" 
         reference "System.ValueTuple/lib/netstandard1.0/System.ValueTuple.dll" 
         includeDir "FSharp.Compiler.Service/lib/netstandard2.0/" 
         reference "FSharp.Compiler.Service/lib/netstandard2.0/FSharp.Compiler.Service.dll" |]

you could use F#5 NuGet reference instead of using NuGet to download packages. I think that it would then only be necessary to reference Suave, TaskBuilder.fs et.c. directly in the documentation.

wallymathieu · 2021-01-24T18:15:19Z

In order to test out such changes you could do:

dotnet tool restore
dotnet build -c Release
dotnet run --project ./docsrc/tool

wallymathieu · 2021-01-24T18:16:46Z

Though perhaps I (or someone willing) should do a separate pull request (once you are finished with this one) with those changes since I think the scope you have for this is to expand the documentation.

wallymathieu · 2021-04-24T18:03:23Z

Since the PR #102 has been merged, is there anything you want to change in this PR?

Gastove · 2021-04-25T04:13:28Z

Ha, I lost track of this. Will review, fix conflicts, etc.

This commit is one possible solution to fsprojects#96. Here, I'm simply dropping support for net461 entirely, in favor of targeting `netstandard`. While I was doing this, I bumped the `netstandard` version to 2.1, but this could easily be an addition instead of a replacement. Similarly, I noted that the `global.json` specified SDK version 3.0, but with a roll-forward directive for newest minor version. Accordingly, I bumped to the newest SDK 3.1 release. These changes meant I could remove the `mono` block from the Fleece solution, so I did. These changes reach all through Fleece, and prompted the replacement of `net461` with `netstandard2.1` (mostly in documentation) or `netcoreapp3.1` (mostly in tests) in many places. While I was doing this, I cleaned whitespace and indentation, and added a missing XML specifier to an fsproj file. On my machine, the build and all tests are passing.

This commit: - Expands the Codec section for DUs to cover non-data-bearing DUs and DUs with type-tags. - Adds a new `further-techniques` doc to cover cases like fields that are required in JSON but not in an F# data model. - Updates the index. - Updates the global.json to SDK version 5.0 to allow F#5 scripting syntax. - Closes fsprojects#98

Gastove · 2021-04-25T19:04:02Z

Okay, that should at least be properly rebased and cleaned up. I had a rather alarming editor snafu, so that was a bit messier than expected, but I think it looks OK now.

I think the last thing I'd love y'all's guidance on is: using released library code versus compiled local assemblies in the docs. Using released library code is considerably more ergonomic; a human contributor doesn't have to remember to do anything before the docs load correctly in an editor. On the other hand, this means there isn't actually exact parity between the docs and the code they document, which doesn't seem great.

A further challenge: when referencing local assemblies, if one updates a dependency version for a particular library, all documentation paths must be updated to the same version. This does enforce correctness, and is just frustrating.

My current thought is:

Nuget reference syntax with versions for external dependencies. (Makes it, if nothing else, easier to spot and update the versions.)
Local DLL reference for Fleece itself.
Documentation making it clear to run a build before loading doc fsx files.

Thoughts from y'all maintainers? What do you prefer?

Gastove · 2021-04-25T19:08:28Z

(Whatever we decide, I'll write some documentation about how to write/contribute documentation and add it to this PR, make sure it's captured clearly.)

wallymathieu · 2021-04-27T20:31:52Z

I think it makes sense to compile the documentation against the source, while having F# 5 NuGet references visible in the docs (for instance via markdown code includes in comments). Though having the docs compile against a released version would imply a separate life cycle of the docs compared compared to the lib: Since you'd have to document new features after a finished release. The reason to tie docs with locally compiled binaries is that you could start document unreleased features.

wallymathieu · 2021-07-23T11:15:31Z

I'm thinking to adjust this PR slightly in order to merge and push documentation. I'll see when I have the time.

wallymathieu

👍

wallymathieu · 2021-07-28T18:47:01Z

I've changed the ShapeD codec definition slightly, what's your thoughts @Gastove ?

docsrc/content/combinators.fsx

docsrc/content/comparison-with-json-net.fsx

wallymathieu · 2021-11-06T08:32:52Z

I'm tinking of fixing the issues in order to be able to merge this PR @Gastove

gusty

Approved with suggestions: we have to deprecate some stuff, but we can do it later, in the PR for Fleece vNext.

docsrc/content/further-techniques.fsx

gusty · 2021-08-04T07:28:53Z

docsrc/content/further-techniques.fsx

+          |> withFields
+          |> jfieldOpt "result"  (fun r -> r.Result)
+          |> jfieldOpt "error"   (fun r -> r.Error)
+          |> jfield    "jsonrpc" (fun _ -> "2.0")


I think we should start deprecating this verbose syntax, in favor of coming Applicative Computation Expressions in Fleece vNext.

For the moment I would use the applicative syntax with operators.

Sounds good. Should we include it in the docs and write that it's obsolete then?

docsrc/content/codec.fsx

docsrc/content/combinators.fsx

docsrc/content/comparison-with-json-net.fsx

wallymathieu · 2021-11-07T09:41:11Z

Many thanks @Gastove for the contribution!

wallymathieu reviewed Jan 24, 2021

View reviewed changes

docsrc/content/codec.fsx Outdated Show resolved Hide resolved

Choc13 mentioned this pull request Mar 4, 2021

Documenting different ways to encode DUs #103

Open

Gastove force-pushed the expand-documentation branch from 3686417 to cf86ec3 Compare April 25, 2021 17:45

Gastove added 3 commits April 25, 2021 14:24

Hrm. Let's try the Chet Husk Reference Assemblies trick again.

8b403b1

Gastove force-pushed the expand-documentation branch from cf86ec3 to a186378 Compare April 25, 2021 18:24

These were somehow re-introduced during rebase, which is incorrect.

867fc72

wallymathieu added 2 commits July 25, 2021 19:38

Minor changes + build docs

057a704

#r nuget

d525ff9

wallymathieu approved these changes Jul 25, 2021

View reviewed changes

wallymathieu added 6 commits July 25, 2021 20:01

+old netcore

51d27a7

+netcore 3

397c6c6

+dotnet tool restore

573e661

+Compile doc src

0783198

Use monad.strict

a1a55a4

jreqValue

f992f55

gusty reviewed Jul 28, 2021

View reviewed changes

docsrc/content/combinators.fsx Outdated Show resolved Hide resolved

gusty reviewed Jul 28, 2021

View reviewed changes

docsrc/content/comparison-with-json-net.fsx Outdated Show resolved Hide resolved

F#+ version in docs

65a59cf

wallymathieu requested a review from gusty November 6, 2021 08:44

gusty approved these changes Nov 6, 2021

View reviewed changes

wallymathieu added 2 commits November 6, 2021 10:04

Merge remote-tracking branch 'origin/master' into expand-documentation

6d267f8

Fixes after codereview

998ad14

gusty merged commit 6158ce1 into fsprojects:master Nov 6, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Expand documentation #100

Expand documentation #100

Gastove commented Jan 23, 2021

Gastove commented Jan 23, 2021

wallymathieu commented Jan 24, 2021

wallymathieu commented Jan 24, 2021

wallymathieu commented Jan 24, 2021

wallymathieu commented Jan 24, 2021

wallymathieu commented Apr 24, 2021

Gastove commented Apr 25, 2021

Gastove commented Apr 25, 2021

Gastove commented Apr 25, 2021

wallymathieu commented Apr 27, 2021

wallymathieu commented Jul 23, 2021

wallymathieu left a comment

wallymathieu commented Jul 28, 2021

wallymathieu commented Nov 6, 2021

gusty left a comment

gusty Aug 4, 2021

wallymathieu Nov 6, 2021

wallymathieu commented Nov 7, 2021

Expand documentation #100

Expand documentation #100

Conversation

Gastove commented Jan 23, 2021

Gastove commented Jan 23, 2021

wallymathieu commented Jan 24, 2021

wallymathieu commented Jan 24, 2021

wallymathieu commented Jan 24, 2021

wallymathieu commented Jan 24, 2021

wallymathieu commented Apr 24, 2021

Gastove commented Apr 25, 2021

Gastove commented Apr 25, 2021

Gastove commented Apr 25, 2021

wallymathieu commented Apr 27, 2021

wallymathieu commented Jul 23, 2021

wallymathieu left a comment

Choose a reason for hiding this comment

wallymathieu commented Jul 28, 2021

wallymathieu commented Nov 6, 2021

gusty left a comment

Choose a reason for hiding this comment

gusty Aug 4, 2021

Choose a reason for hiding this comment

wallymathieu Nov 6, 2021

Choose a reason for hiding this comment

wallymathieu commented Nov 7, 2021