F# Formatting version 20

With its recent release of major version 20, we want to highlight F# Formatting. Used to generate documentation, or for creating literate scripts, it is a tool which will benefit anybody who wants to communicate technical concepts. Get great results with minimal effort due to solid default settings and wonderful documentation. F# Formatting can do LaTeX typesetting (using MathJax) so it is also useful for mathematical or scientific documents.

Get up and runnning in 3 simple steps:

dotnet tool install --local fsdocs-tool
Create docs/index.md
dotnet fsdocs watch

Running the tool in watch mode like this will launch a browser pointing at your freshly generated docs. As you make changes, the page will hot reload so you can see them immediately. It really couldn't be much simpler than that!

Literate script example

As an example, let's write a quick primer on some of F#'s mathematical operators.

First, let's create docs/Operators.fsx and add some F# code.

let a = 4.0
let b = 10.0
[
    a + b // Addition
    a - b // Subtraction
    a * b // Multiplication
    a / b // Division

]
(*** include-it ***)

We can see the new page at http://localhost:8901/Operators.html and the special comment (*** include-it ***) shows the value of the recently evaluated expression ...only we are not evaluating anything yet, so instead we get a warning!

Warning: Output, it-value and value references require --eval

To actually run the code and see runtime values, we re-run the tool with the --eval flag.

dotnet fsdocs watch --eval

Finally, there's not a lot of point using a literate script solely for rendering out code, so let's add some prose to give context. We can use markdown, but since markdown is not generally valid F# code, we put it inside a multi-line comment with an extra asterisk at the start.

(**
# Operators
## Simple mathematical operators
Addition, subtraction, multiplication and division are comprised of `+`, `-`, `*` and `/` respectively.
*)

And the fruits of our labour:

As you can see F# formatting makes formatting your documentation a breeze. Check out their extensive documentation for its full range of features!