FSharp.Core API documentation generation

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

Contributing to Library Content

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

• Fork and clone https://github.com/dotnet/fsharp locally, see below, as a subdirectory of your copy of fsharp-core-docs

• Contribute to the FSharp.Core directory

• Submit work to main branch of https://github.com/dotnet/fsharp

• Update the dotnet tool if new versions are released.

Contributing to Generation of API Docs

The docs are generated by using fsdocs tool from FSharp.Formatting. If you want to improve the generation process:

• Contribute to the API Docs mode and/or HTML generator in FSharp.Formatting.ApiDocs and the fsdocs tool

• Submit work to the main branch of https://github.com/fsprojects/FSharp.Formatting

• Update the dotnet tool if new versions are released.

Build steps

dotnet tool restore
dotnet restore FSharp.Core
dotnet fsdocs build

For now, we want to pick up the latest copies of FSharp.Formatting and FSharp.Core, and set you up to make contributions to these. So we ask you to clone local copies of these:

(start in 'fsharp-core-docs')
dotnet restore FSharp.Core
dotnet tool restore

(make fsharp-compiler-docs/fsharp)
git clone https://github.com/dotnet/fsharp --depth 1 -b main

(build 'fsharp-core-docs/fsharp')
pushd fsharp
dotnet build src\FSharp.Core\FSharp.Core.fsproj /p:BUILDING_USING_DOTNET=true
popd

Then do iterative development using:

(from 'fsharp-core-docs')
dotnet fsdocs watch --sourcefolder fsharp

CI Pipeline

This repo is published via GitHub Actions. On each push to main, the docs are built, 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, so once the generated files are pushed the update is nearly-instant.

To build the very latest and freshest docs the CI does this:

1. build dotnet/fsharp main branch (where we assume latest doc updates have been pushed).

2. generate the documentation using the local dotnet fsdocs tool.