FSharp.Compiler.Service documentation generation

https://fsharp.github.io/fsharp-compiler-docs

Contributing to Library Content

To improve the content of the FSharp.Compiler.Service library documentation, contribute to the XML /// documentation in the signature files (*.fsi) in the FSharp.Compiler.Service implementation.

• Fork and clone https://github.com/dotnet/fsharp locally, see below

• Contribute to docs directory and src/Compiler directory and submit work to main branch of dotnet/fsharp

• Once accepted your work will be published through a rebuild here. A rebuild is triggered daily at 17:30 UTC or you can trigger it yourself by submitting a dummy change.

The docs are generated by using fsdocs tool from FSharp.Formatting.

Build steps

Everything is driven by build.fsx, a Fun.Build script. You need a .NET 10 SDK to run it. The default pipeline does the following:

1. Clones dotnet/fsharp (shallow, main branch) into the git-ignored fsharp folder, unless it already exists.

2. Builds FSharp.Compiler.Service.slnx with the SDK that fsharp/global.json pins, using dotnet/fsharp's own eng/common/dotnet.sh bootstrap so that SDK does not need to be on your PATH.

3. Restores the fsdocs tool and the FSharp.Compiler.Service project in this repo.

4. Runs fsdocs build against fsharp/docs and writes the site to output.

   dotnet fsi build.fsx

To pick up new upstream changes, delete the fsharp folder and run the pipeline again.

To generate the docs from a dotnet/fsharp checkout you already have, for example a fork with docs changes in progress, point FSHARP_REPO at it. The clone step is skipped and that checkout is built and read in place:

FSHARP_REPO=~/Projects/fsharp dotnet fsi build.fsx

Once a build has run, iterate on the docs with live reload:

dotnet fsi build.fsx -- -p Watch

Anything after the pipeline name is passed on to fsdocs watch, for example -- -p Watch --nolaunch --port 8080.

Run dotnet fsi build.fsx -- -h to list the pipelines.

CI Pipeline

This repo is published via GitHub Actions. On each push to main, build.fsx runs, and the outputs (which are written to the output directory by fsdocs) are pushed to the gh-pages branch. This repo is configured to host using GitHub Pages from this branch.