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

• Contribute to the FSharp.Core directory

• Use a local build, see below

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

• Once accepted your work will be published through a rebuild here, so submit a dummy pull request here

Contributing to Generation of API Docs

The docs 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

• Use a local copy of these, see below

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

• Once accepted the new tooling will be published through a rebuild here, so submit a dummy pull request here

Contributing to Layout and Design

These pages are currently using the default template of the FSharp.Formatting tools with its small amount of corresponding CSS and JavaScript

This template is not the long term plan (unless it is improved enough). We can and must improve the design. Please help with this, and please be bold. This can be done in two ways:

1. Copy the template and/or any of the CSS or JavaScript to docs/_template.html and a new directory docs/content. Now make changes and rebuild as before. Your template will be used instead of the default template.

2. After you have identified fixes and improvements, contribute back to the default template of FSharp.Formatting, or submit your work here and we can assess that for you. If your design is good enough it might become the default design for all F# libraries.

Build steps

Eventually the build will just be

dotnet tool restore
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:

git clone https://github.com/dotnet/fsharp --depth 1 -b feature/docs
git clone https://github.com/fsprojects/FSharp.Formatting
pushd fsharp
.\build -noVisualStudio
popd

pushd FSharp.Formatting
.\build
popd

Then do iterative development using:

FSharp.Formatting\src\FSharp.Formatting.CommandTool\bin\Debug\netcoreapp3.1\fsdocs.exe watch --sourcefolder fsharp 

CI Pipeline

This repo is published via GitHub Actions. On each push to master, 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 using the latest fsdocs tooling the CI does this:

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

2. builds FSharp.Formatting master branch

3. Uses that FSharp.Formatting tool to build the docs for the FSharp.Core built in step 1