End-user documentation

[nojaf]

We need a section in the documentation on how they can start using Fantomas.

This should cover:

• The installation from the dotnet tool.
• Initial usage from the command line.
• Usage in the editor (VsCode, VisualStudio, Rider), the important bit here is that the user should be aware what version of Fantomas is being used in the editor.
• Formatting check during CI. How to do it and why it matters
• .editorconfig support and an overview of all the settings. It would be nice if we can have some sort of generated code samples that are always up to date.
• dotFantomas ignore file
• Git hooks

A lot of topics are somewhat covered in https://github.com/fsprojects/fantomas/blob/master/docs-old/Documentation.md but we need to revisit and chop everything into logical units.

[nojaf]

@yisusalanpng I've been exploring what we could do with the settings documentation page.

If you add a file meh.fsx in the docs folder and run dotnet fsdocs watch --eval. (Notice that --eval flag).

You can write some F# code that gets evaluated by FsDocs. Something like:

(**
---
---
# Some text, content of meh.fsx
*)

#r "nuget: Fantomas.Core, 5.0.0-alpha-*"

open Fantomas.Core.FormatConfig
open Fantomas.Core

(**

## MaxRecordWidth

*)

let input = 
    """
    type X = {
        Y :  int
        Z :  string
    }
    """

let config = { FormatConfig.Default with MaxRecordWidth = 2 }
let result1 =
    CodeFormatter.FormatDocumentAsync(false, input, config)
    |> Async.RunSynchronously

(*** include-value: result1 ***)

gets transformed to

(Note that I did had to copy some CSS from the default style sheet:

/*--------------------------------------------------------------------------
  Formatting pre and code sections in fsdocs-content (code highlighting is
    further below)
/*--------------------------------------------------------------------------*/

#fsdocs-content code {
    /* font-size: 0.83rem; */
    font: 0.85rem 'Roboto Mono', monospace;
    background-color: #f7f7f900;
    border: 0px;
    padding: 0px;
    /* word-wrap: break-word; */
    /* white-space: pre; */
}

/* omitted */
#fsdocs-content span.omitted {
    background: #3c4e52;
    border-radius: 5px;
    color: #808080;
    padding: 0px 0px 1px 0px;
}

#fsdocs-content pre .fssnip code {
    font: 0.86rem 'Roboto Mono', monospace;
}

#fsdocs-content table.pre,
#fsdocs-content pre.fssnip,
#fsdocs-content pre {
    line-height: 13pt;
    border: 0px solid #d8d8d8;
    border-top: 0px solid #e3e3e3;
    border-collapse: separate;
    white-space: pre;
    font: 0.86rem 'Roboto Mono', monospace;
    width: 100%;
    margin: 10px 0px 20px 0px;
    background-color: #f3f4f7;
    padding: 10px;
    border-radius: 5px;
    color: #8e0e2b;
    max-width: none;
    box-sizing: border-box;
}

#fsdocs-content pre.fssnip code {
    font: 0.86rem 'Roboto Mono', monospace;
    font-weight: 600;
}

#fsdocs-content table.pre {
    background-color: #fff7ed;
}

#fsdocs-content table.pre pre {
    padding: 0px;
    margin: 0px;
    border-radius: 0px;
    width: 100%;
    background-color: #fff7ed;
    color: #837b79;
}

#fsdocs-content table.pre td {
    padding: 0px;
    white-space: normal;
    margin: 0px;
    width: 100%;
}

#fsdocs-content table.pre td.lines {
    width: 30px;
}


#fsdocs-content pre {
    word-wrap: inherit;
}

.fsdocs-example-header {
    font-size: 1.0rem;
    line-height: 1.375rem;
    letter-spacing: 0.01px;
    font-weight: 700;
    color: #262626;
}

/*--------------------------------------------------------------------------
  Formatting for F# code snippets
/*--------------------------------------------------------------------------*/

.fsdocs-param-name,
.fsdocs-return-name,
.fsdocs-param {
    font-weight: 900;
    font-size: 0.85rem;
    font-family: 'Roboto Mono', monospace;
}
/* strings --- and stlyes for other string related formats */
#fsdocs-content span.s {
    color: #dd1144;
}
/* printf formatters */
#fsdocs-content span.pf {
    color: #E0C57F;
}
/* escaped chars */
#fsdocs-content span.e {
    color: #EA8675;
}

/* identifiers --- and styles for more specific identifier types */
#fsdocs-content span.id {
    color: #262626;
}
/* module */
#fsdocs-content span.m {
    color: #009999;
}
/* reference type */
#fsdocs-content span.rt {
    color: #4974D1;
}
/* value type */
#fsdocs-content span.vt {
    color: #43AEC6;
}
/* interface */
#fsdocs-content span.if {
    color: #43AEC6;
}
/* type argument */
#fsdocs-content span.ta {
    color: #43AEC6;
}
/* disposable */
#fsdocs-content span.d {
    color: #43AEC6;
}
/* property */
#fsdocs-content span.prop {
    color: #43AEC6;
}
/* punctuation */
#fsdocs-content span.p {
    color: #43AEC6;
}
#fsdocs-content span.pn {
    color: #262626;
}
/* function */
#fsdocs-content span.f {
    color: #e1e1e1;
}
#fsdocs-content span.fn {
    color: #990000;
}
/* active pattern */
#fsdocs-content span.pat {
    color: #4ec9b0;
}
/* union case */
#fsdocs-content span.u {
    color: #4ec9b0;
}
/* enumeration */
#fsdocs-content span.e {
    color: #4ec9b0;
}
/* keywords */
#fsdocs-content span.k {
    color: #b68015;
    /* font-weight: bold; */
}
/* comment */
#fsdocs-content span.c {
    color: #808080;
    font-weight: 400;
    font-style: italic;
}
/* operators */
#fsdocs-content span.o {
    color: #af75c1;
}
/* numbers */
#fsdocs-content span.n {
    color: #009999;
}
/* line number */
#fsdocs-content span.l {
    color: #80b0b0;
}
/* mutable var or ref cell */
#fsdocs-content span.v {
    color: #d1d1d1;
    font-weight: bold;
}
/* inactive code */
#fsdocs-content span.inactive {
    color: #808080;
}
/* preprocessor */
#fsdocs-content span.prep {
    color: #af75c1;
}
/* fsi output */
#fsdocs-content span.fsi {
    color: #808080;
}

/* tool tip */
div.fsdocs-tip {
    background: #475b5f;
    border-radius: 4px;
    font: 0.85rem 'Roboto Mono', monospace;
    padding: 6px 8px 6px 8px;
    display: none;
    color: #d1d1d1;
    pointer-events: none;
}

div.fsdocs-tip code {
    color: #d1d1d1;
    font: 0.85rem 'Roboto Mono', monospace;
}

, to get the colouring of the code correct)

[alanlomeli]

looks good! thanks nojaf :)

[nojaf]

@yisusalanpng I've been thinking about this some more. Here are some suggestions:

• Start with an introductory paragraph on how .editorconfig works. How both the command-line and editors respect this.
• Split up the list of settings into some categories: "Auxilary settings", "Maximum width constraints", "G-Research style" & "Other"
• Remove the listing of all the default values, people seem to copy those anyway even though we mention that shouldn't do this.
• fsharp_strict_mode should still be the last setting.
• Make sure all settings are searchable. Entering indent_size in the search bar should lead people to the right section.
• Try to make the page a script file as mentioned above. The examples should be rendered from the actual formatting.
• 🟩🟨🟥 I would also like to have a recommendation system for each setting. We basically want to tell the users which settings are ok to change from the defaults. For example fsharp_multiline_block_brackets_on_same_column is part of the MS F# style guide as well (*). And maybe we want a G-Research guide icon as well? fsharp_strict_mode should never be used by users. And it is totally fine to update fsharp_max_record_width. Please come up with a system we can use to indicate this. I'll go over each setting afterwards.

(*) Although in Fantomas we've implemented it according to the G-Research guide and there is a subtle difference between both guides. Yadda yadda yadda 😸.

[nojaf]

@alanlomeli I think the remaining todo's here are:

• Connect each page with the next and previous links
• Visual Studio page:
  • Update the VS for Mac section
  • Verify if the guidance for both VS and VS for Mac is sufficient.
• Rider page:
  • Repeat the Fantomas info found at https://www.jetbrains.com/rider/whatsnew/#f-support
  • The existing problem of overridden settings in Rider hasn't been reported anywhere, so we don't need to mention it in our docs.
• VSCode:
  • Mention if works out of the box, similar to VS.
  • Maybe explain how it will detect the Fantomas version. You can find the algorithm in https://github.com/fsprojects/fantomas/blob/30f73bc1c805d0c09e3cb7a268b5f71cb0e7ef38/src/Fantomas.Client/FantomasToolLocator.fs#L173-L195

And the general gist will be: is it clear for people how to get started after all these pages?

[nojaf]

Well done @alanlomeli!