[WIP] Build docs using 'fsdocs' tooling

.config/dotnet-tools.json

@@ -2,16 +2,22 @@
   "version": 1,
   "isRoot": true,
   "tools": {
+    "fsharp.formatting.commandtool": {
+      "version": "6.1.0",
+      "commands": [
+        "fsdocs"
+      ]
+    },
     "paket": {
-      "version": "5.245.2",
+      "version": "5.247.4",
       "commands": [
         "paket"
       ]
     },
-    "fornax": {
-      "version": "0.13.1",
+    "fake-cli": {
+      "version": "5.20.2",
       "commands": [
-        "fornax"
+        "fake"
       ]
     }
   }

.github/workflows/docs.yml

@@ -24,12 +24,20 @@ jobs:
       run: dotnet tool restore
     - name: Restore dependencies
       run: dotnet paket restore
-    - name: Run Fornax
-      run: dotnet fornax build
+    - name: Checkout fsharp master
+      run: git clone https://github.com/dotnet/fsharp --depth 1 fsharp -b feature/docs
+    - name: Build fsharp master
+      run: cd fsharp && .\build -noVisualStudio
+    - name: Checkout FSharp.Formatting master
+      run: git clone https://github.com/dotnet/FSharp.Formatting --depth 1 FSharp.Formatting 
+    - name: Build FSharp.Formatting master
+      run: cd FSharp.Formatting && .\build -t Build
+    - name: Run fsdocs
+      run: FSharp.Formatting\src\FSharp.Formatting.CommandTool\bin\Release\netcoreapp3.1\fsdocs.exe build --sourcefolder fsharp
     - name: Deploy
       uses: peaceiris/actions-gh-pages@v3
       with:
         personal_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: ./_public
+        publish_dir: ./output
         publish_branch: gh-pages
         force_orphan: true

FSharp.Core/FSharp.Core.fsproj

@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>netstandard2.0</TargetFramework>
+    <Authors>F# Software Foundation; Microsoft; F# Contributors</Authors>
+    <Summary>The core library for F#</Summary>
+    <Description>The core library F#</Description>
+    <Copyright>Copyright 2003-2020</Copyright>
+    <PackageLicenseUrl>https://github.com/dotnet/fsharp/blob/master/License.txt</PackageLicenseUrl>
+    <PackageProjectUrl>https://fsharp.github.io/fsharp-core-api-docs/</PackageProjectUrl>
+    <PackageIconUrl>https://fsharp.org/img/logo/fsharp128.png</PackageIconUrl>
+    <PackageTags>F#;async;fsharp;streaming</PackageTags>
+    <IncludeSymbols>true</IncludeSymbols>
+    <RepositoryUrl>https://github.com/dotnet/fsharp/</RepositoryUrl>
+    <RepositoryType>git</RepositoryType>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
+    <OutputType>Library</OutputType>
+    <IsTestProject>false</IsTestProject>
+    <IsPackable>true</IsPackable>
+    <PackageLicenseExpression>MIT</PackageLicenseExpression>
+    <PackageVersion>4.7.2</PackageVersion>
+    <DisableImplicitFSharpCoreReference>true</DisableImplicitFSharpCoreReference>
+    <!-- <TargetPath>$(MSBuildThisFileDirectory)..\packages\FSharp.Core\lib\netstandard2.0\FSharp.Core.dll</TargetPath> -->
+
+    <!-- for a parallel checkout and build of fsharp  -->
+    <TargetPath Condition="Exists('..\..\fsharp\build.cmd')">$(MSBuildThisFileDirectory)..\..\fsharp\artifacts\bin\FSharp.Core\Debug\netstandard2.0\FSharp.Core.dll</TargetPath>
+
+    <!-- for a local checkout and build of fsharp in CI -->
+    <TargetPath Condition="Exists('..\fsharp\build.cmd')">$(MSBuildThisFileDirectory)..\fsharp\artifacts\bin\FSharp.Core\Debug\netstandard2.0\FSharp.Core.dll</TargetPath>
+  </PropertyGroup>
+</Project>
+

README.md

@@ -2,16 +2,38 @@
 
 https://fsharp.github.io/fsharp-core-api-docs/
 
-## Build steps:
+## Build steps
 
-* dotnet tool restore
-* dotnet paket restore
+Have a build of https://github.com/dotnet/fsharp in a parallel directory, e.g.
+
+    git clone https://github.com/dotnet/fsharp --depth 1
+    cd fsharp
+    .\build
+
+Then
+
+    dotnet tool restore
+    dotnet paket restore
+    dotnet fsdocs build --sourcefolder ../fsharp
+
+For iterative development use:
+
+    dotnet fsdocs watch --sourcefolder ../fsharp --open reference/index.html
+
+Change the `TargetPath` in our local `FSharp.Core.fsproj` if needed to picl up a different build of FSHarp.Core.
+
+    <TargetPath>$(MSBuildThisFileDirectory)..\..\fsharp\artifacts\bin\FSharp.Core\Debug\netstandard2.0\FSharp.Core.dll</TargetPath>
 
-from here, if you're trying to do a one-off build, run:
-* dotnet fornax build
-otherwise, for a more interactive hot-reload experience run:
-* dotnet fornax watch
 
 ## CI Pipeline
 
-This repo is published via GitHub Actions. On each push to master, `dotnet fornax build` is run, and the outputs (which are written to the `_public` directory by fornax) 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.
+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
+