search

fsprojects / FSharp.Formatting

F# tools for generating documentation (Markdown processor and F# code formatter)
https://fsprojects.github.io/FSharp.Formatting/
Other
462 stars 156 forks source link

Update docs for v3.0 #490

Closed dsyme closed 4 years ago

dsyme commented 5 years ago

I'm looking to move some repos to use "modern" FSharp.Formatting, which I assume means v3.0. However I can't find even the most basic getting started docs - the doc site still says

Assuming you are using FSharp.Formatting 2.8.0 typical build.fsx looks like this...

So basic questions

Thanks

dsyme commented 5 years ago

To be honest, I think we need to somehow really radically simplify the usage model for FSharp.Formatting for literate programming and doc generation.

Currently the getting-started approach seems to still require using a generate.fsx script like this one used in this repo.

This is a disaster.

  1. These scripts are crazily fragile and honestly should never have been allowed to proliferate through the F# ecosystem - we should never have added this to the F# project scaffolding.

  2. These scripts are a very strange mishmash between FAKE scripts and applications and so on. They have their own WATCH logic and other multiple #if. It's really a major problem.

  3. The dependency management in these scripts is brutal, as the script processing tool is itself a script which processes other scripts. It's incredibly hard to work out what's going on.

I'm really concerned about this as many important F# repos use FSharp.Formatting but are normally stuck on incredibly ancient versions of that tool - and also stuck using Mono and .NET Framework to process these doc files.

My recommendation would be that we somehow find something much much simpler. I'm not quite sure what - ideally simply dotnet fake docs or some simply entry in a FAKE build script for building standard F# docs in standard ways.

matthid commented 5 years ago

What is the usage model for FSharp.Formatting in v3.0?

Can you clarify what you mean? I don't feel like it should change to v2. However, it could very well change for technical reasons (and honestly it is not unlikely, but we don't know yet)

Are .NET Framework/Mono scripts still used, or can you use FAKE scripts?

I'd assume both should work. There are some corner cases when dependencies clash between the host and FSF. Especially in FAKE 4. In the future, we should implement https://github.com/fsprojects/FSharp.Formatting/issues/474 (which apparently has been done partly already; not sure if there is anything left) to do https://github.com/fsharp/FAKE/issues/2043

Where is the simplest getting started example?

I'm not aware of any up2date one. I saw https://thinkbeforecoding.com/post/2018/12/07/full-fsharp-blog additionally we have https://github.com/fsprojects/FSharp.Formatting/blob/master/docs/content/upgrade_from_v2_to_v3.md

Which repos used FSharp.Formatting v3.0 today?

Fake uses latest. The easiest is to use the CommandLine package and execute the tool. This decouples stuff and works in a '.NETCore' world as long as .NET or Mono is installed. See https://github.com/fsprojects/FSharp.Formatting/issues/453

Regarding v3

There are several things which I think should be part of v3 as they might introduce breaking changes.

Imho we should have these three things sorted out before releasing. Otherwise, we might break people multiple times. I guess if enough people indicate that this is fine, we could release right away as well.

I think once we have those things it is more clear which documentation we need, which is hard to predict at this time.

EDIT: Just saw your recent comment and I agree with the problem analysis and the solution (In fact a long time ago). My suggestions are to use standalone (limited configuration) and/or integrate into FAKE 5 and letting paket find a resolution. Standalone is good for the transition until we have sorted out everything.

dsyme commented 5 years ago

@matthid Have you considered dropping all support for .NET Framework and Mono in the doc generation process, only allowing doc generation where

I think this would greatly simplify our life going forward.

For usage, I'm imagining we ultimately have the usage model as something like:

dotnet build /t:Docs

which by default does all the normal generate.fsx things, looking in docs for content and building reference docs against any generated assemblies. The actual generation process would be entirely hidden (no generate.fsx).

matthid commented 5 years ago

Have you considered dropping all support for .NET Framework and Mono in the doc generation process

I have not, and I'm not strictly against it either. It's just that we need to do some work ... We need to evaluate what exactly we gain.

dotnet build /t:Docs

Again not against that usage model. But as far as I can tell nobody likes fiddling around with MSBuild. From experience, the MSBuild integration of Paket is already a massive source of bugs, so in the end, it might be more work ;) I guess it all boils down to finding somebody who wants to get their hands dirty and send a PR...

dsyme commented 5 years ago

Again not against that usage model. But as far as I can tell nobody likes fiddling around with MSBuild. From experience, the MSBuild integration of Paket is already a massive source of bugs, so in the end, it might be more work ;)

Yes, I understand. What would be the one-line usage model that you'd expect from FAKE?

thinkbeforecoding commented 5 years ago

I worked on this. The cli tool is still using netfx/mono due to razor integration.

The Fsharp.Litterate nuget contains all the parsing, executions, formatting, for netstandard2.0 but not the templating.

I've been using this along with a fake 5 scripts that does the templating using fable react nuget. It is used as static html templating engine with templates written in an elmish view way.

See my blog for the steps: https://thinkbeforecoding.com/post/2018/12/07/full-fsharp-blog

baronfel commented 5 years ago

In Miniscaffold we actually use React in the same way. @thinkbeforecoding your blog was actually the inspiration for our work in Miniscaffold

thinkbeforecoding commented 5 years ago

And by the way, this blog post has been generated this way 😋

thinkbeforecoding commented 5 years ago

For less advanced usages, it should be easy to do the same way but use a different still simple template engine and package it as a cli tool

dsyme commented 5 years ago

Based on updating the doc generation process for FsLexYacc and FSharp.Formatting, I recommend that no generate.fsx script should ever be a FAKE script nor reference FAKE libraries.

Both FAKE and FSharp.Formatting use FSharp.Compiler.Service.dll. The collision of dependencies is a disaster.

Let's just make all future generate.fsx plain vanilla F# Interactive scripts - and indeed aim to get rid of them altogether.

matthid commented 5 years ago

Yes, I understand. What would be the one-line usage model that you'd expect from FAKE?

I guess that is decided by the person doing the work or sending the pull request. Personally, I think it should be a matter of adding a NuGet package to the FAKE build script and calling a function, where you can override parameters or leave the defaults (just like other functions look like in FAKE).

I recommend that no generate.fsx script should ever be a FAKE script nor reference FAKE libraries. Both FAKE and FSharp.Formatting use FSharp.Compiler.Service.dll. The collision of dependencies is a disaster. Let's just make all future generate.fsx plain vanilla F# Interactive scripts - and indeed aim to get rid of them altogether.

I disagree, that problem only appears in FAKE 4 and is solved by FAKE 5. It's just that FSharp.Formatting is not ready to be used in FAKE 5.

dsyme commented 5 years ago

I disagree, that problem only appears in FAKE 4 and is solved by FAKE 5. It's just that FSharp.Formatting is not ready to be used in FAKE 5.

OK, that's great to know - what was the solution to this problem again?

matthid commented 5 years ago

Well, the problem was sharing assemblies between the "runtime"/"host" and the "script". FSharp.Compiler.Service was only one such instance. We had problems with for example Newtonsoft.Json as well. The solution is to no longer share assemblies but instead, use something called an "AssemblyLoadContext" which is very similar to AppDomains in the full framework (but more lightweight). The only assemblies we share are the framework ones and FSharp.Core. While FSharp.Core already has given some edge cases, and ideally, I'd like to get rid of it, because of the high compat bar of FSharp.Core it is OKish and FAKE will warn if there is a mismatch which could lead to errors.

dsyme commented 4 years ago

This has been solved, the docs are updated as I understand things