FSharp.Formatting vNext

[cloudRoutine]

The current implementation of FSharp.Formatting is highly dependent upon Razor and isn't setup in an easily extensible manner. I think this has held back the usefulness of FSharp.Formatting, and limited the contexts and types of documents its been used to create.

I think we could use the architecture of DocFx as inspiration for a more powerful FSharp.Formatting

Reorienting FSharp.Formatting as a documentation production pipeline that can support multiple input parsers for a variety of formats (e.g. specific extended markdown formats) that can feed into multiple output producers could extend FSharp.Formatting's range into epubs, pdfs, or any other format users are willing to build support for.

One of the main things I'd like to work towards is improving liquid templating support and providing a wider range of options for producing API pages. If these could be packaged with Fable plugins to add features like search and search via type signature we could greatly improve the usability of F# API pages. Taking it a step further we could set up documentation production so that it fully includes source code tied to a specific release version and have sourcelink link to these static source code release pages so that the links would always take you to the source code that produced the dll. This could be improved even further by adding full intellisense and systax highlighting to the static source pages that are produced. The most extreme version of these advanced API pages could be created with a limited version of monaco built in to enable find all references, code peek, and many of the other editor features we've come to love in vscode.

Template Processing

• Handlebars Markup Template
  • Processor - Handlebars.Net

Reference Libraries

• SourceBrowser
• DocFx
• SourceLink

Into The Future

A dotnet cli tool for documentation production

[tpetricek]

I would not want to turn F# Formatting into a pipeline with plugins. It should not be a framework, but a library.

I think it's fine if more complex pipeline is built on top of it, but F# Formatting itself should be doing just the basic things that are needed for that:

• Parsing markdown documents with F# snippets
• Parsing F# script files with Markdown comments
• Reading .NET metadata from DLLs with matching XML docs

Currently, some of these directly invoke Razor and that's wrong. Instead, the core of F# Formatting should be just a library that does the above and returns some F# objects (domain model) with the information it got.

So the first step is to remove Razor dependency and define the domain models, so that the core library can do just this. On top of this, we can then rebuild the current processing (used by ProjectScaffold) and an alternative one based on DotLiquid (or anything else).

[cloudRoutine]

@tpetricek will that still leave it open to use alternative markdown processors? let's say I wanted to use MarkDig instead of the current markdown parser

[tpetricek]

If the transformation pipeline is split into a number of steps, then you should be able to use MarkDig and then turn the AST they produce into the appropriate F# types....

[tpetricek]

(sorry, wrong button)

[cloudRoutine]

Cool, a redesign with extensibility and flexibility in mind was my main concern. Whether that was via plugin interfaces or making library calls in a new project that serves as the "pipeline" was fine 😸

[cloudRoutine]

@tpetricek should I wait until #417 is merged before starting to work on this?

[tpetricek]

@cloudRoutine I think you can just base this on the code in the #417 branch.

I think the first step would be to define the F# domain model for the data to be exported by the F# Formatting components, so perhaps we could do that here on GitHub /in Gists/@fssnippets so that we agree on what the result should look like first?

[rmunn]

One thing I'd like to see in FSharp.Formatting -- and this issue may or may not be the best place to discuss it -- is a clear, obvious way to insert usage examples into API documentation. The FAKE documentation would be one place that would really benefit from some good usage examples (I've found it quite hard to find the right function for what I need among the thousand+ functions that FAKE offers), and I'm sure there are other projects that would benefit as well. If usage examples could get type-information tooltips, that would be even better, but the first step is figuring out what they would look like.

[matthid]

I think it's fine if more complex pipeline is built on top of it, but F# Formatting itself should be doing just the basic things that are needed for that:

Parsing markdown documents with F# snippets
Parsing F# script files with Markdown comments
Reading .NET metadata from DLLs with matching XML docs

Currently, some of these directly invoke Razor

@tpetricek It's kind of true, but the code is actually already quite separated/"clean". It's only a matter of refactoring to split the functionalities apart.

The only 2 places where Razor is actually used are

• here the parsing is basically already done and we directly invoke razor (as default). We could replace ctx.OutputType with a lambda, essentially replacing the hardcoded generateFile function.
• here basically the razor part starts for the MetadataFormat. We basically could extract all above into a seperate function without razor dependency and returning the resolved docs data structures.

Generally I like the idea of simplifying the core and making those more accessible to other scenarios.

[aloisdg]

Hello,

Do you plan to move to dotnet core? You talk about dotnet cli so I guess the answer is yes. :)

[dsyme]

Closing old issue