Migrate documentation to docfx

.github/workflows/release_documentation.yml

@@ -12,22 +12,22 @@ jobs:
       - name: Setup .NET
         uses: actions/setup-dotnet@v4
         with:
-          dotnet-version: 9.0.x
+          dotnet-version: |
+            9.0.x
+            8.0.x
 
-      - name: Setup Ruby for documentation build
-        uses: ruby/setup-ruby@v1
-        with:
-          ruby-version: '3.2'
-          bundler-cache: true
+      - name: Setup docfx
+        run: dotnet tool install -g docfx
 
       - name: Build documentation
-        run: dotnet run --project 'build/build.fsproj' -- -t Documentation
+        run: docfx build
+        working-directory: ./docs
 
       - name: Upload documentation
         uses: actions/upload-artifact@v4
         with:
           name: docs
           path: |
-            bin/Release/nsubstitute.github.com/
+            ./docs/_site
           retention-days: 7
           compression-level: 9

.github/workflows/test.yml

@@ -46,15 +46,8 @@ jobs:
             9.0.x
             8.0.x
 
-      # used for documentation
-      - name: Setup Ruby
-        uses: ruby/setup-ruby@v1
-        with:
-          ruby-version: '3.2'
-          bundler-cache: true
-
       - name: Build documentation
-        run: build\build.cmd --target Documentation
+        run: dotnet run --project 'build/build.fsproj'
 
   format-verify:
     runs-on: ubuntu-latest

build/build.fs

@@ -1,9 +1,6 @@
-open System
-open System.Diagnostics
 open System.IO
 
 open Fake.Core
-open Fake.Core.TargetOperators
 open Fake.DotNet
 open Fake.IO
 open Fake.IO.Globbing.Operators
@@ -54,18 +51,18 @@ let initTargets() =
         let outputCodePath = output </> "CodeFromDocs"
         Directory.create outputCodePath
         // generate samples from docs
-        ExamplesToCode.Convert [ root </> "docs/"; root </> "docs/help/_posts/"; root ] outputCodePath
+        ExamplesToCode.Convert [ root </> "docs/"; root </> "docs/docs"; root ] outputCodePath
         // compile code samples
         let csproj = """
             <Project Sdk="Microsoft.NET.Sdk">
             <PropertyGroup>
-                <TargetFrameworks>net6.0;net462</TargetFrameworks>
+                <TargetFrameworks>net8.0;net462</TargetFrameworks>
                 <LangVersion>latest</LangVersion>
             </PropertyGroup>
             <ItemGroup>
-                <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.8.0" />
+                <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.12.0" />
                 <PackageReference Include="NUnit" Version="3.14.0" />
-                <PackageReference Include="NUnit3TestAdapter" Version="4.5.0" />
+                <PackageReference Include="NUnit3TestAdapter" Version="4.6.0" />
             </ItemGroup>
             <ItemGroup>
                 <ProjectReference Include="..\..\..\src\NSubstitute\NSubstitute.csproj" />
@@ -78,41 +75,6 @@ let initTargets() =
         DotNet.build (fun p -> p) projPath
         DotNet.test (fun p -> p) projPath
 
-    let tryFindFileOnPath (file : string) : string option =
-        Environment.GetEnvironmentVariable("PATH").Split([| Path.PathSeparator |])
-        |> Seq.append ["."]
-        |> fun path -> ProcessUtils.tryFindFile path file
-
-    Target.description("Build documentation website. Requires Ruby, bundler and jekyll.")
-    Target.create "Documentation" <| fun _ -> 
-        Trace.log "Building site..."
-        let exe = [ "bundle.bat"; "bundle" ]
-                    |> Seq.map tryFindFileOnPath
-                    |> Seq.collect (Option.toList)
-                    |> Seq.tryFind (fun _ -> true)
-                    |> function | Some x -> Trace.log ("using " + x); x
-                                | None   -> Trace.log ("count not find exe"); "bundle"
-
-        let workingDir = root </> "docs/"
-        let docOutputRelativeToWorkingDir = ".." </> output </> "nsubstitute.github.com"
-
-        // TODO migrate the following to FAKE API: CreateProcess.ofStartInfo(p)
-        // https://fake.build/apidocs/v5/fake-core-createprocess.html
-        // that doesn't work for some reason
-        let p = ProcessStartInfo(
-                        UseShellExecute = false,
-                        CreateNoWindow = true,
-                        FileName = exe,
-                        WorkingDirectory = workingDir,
-                        Arguments = "exec jekyll build -d \"" + docOutputRelativeToWorkingDir + "\"")
-        let proc = Process.Start(p)
-        proc.WaitForExit()
-        let result = proc.ExitCode
-        if result = 0 then
-            "Site built in " + docOutputRelativeToWorkingDir |> Trace.log
-        else
-            "failed to build site" |> failwith
-
     Target.description("List targets, similar to `rake -T`. For more details, run `--listTargets` instead.")
     Target.create "-T" <| fun _ ->
         printfn "Optional config options:"
@@ -121,8 +83,6 @@ let initTargets() =
         printfn ""
         Target.listAvailable()
 
-    "Documentation" <== [ "TestCodeFromDocs" ]
-
 [<EntryPoint>]
 let main argv =
     argv

build/build.fsproj

@@ -7,8 +7,6 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <None Include="build.cmd" />
-    <None Include="build.sh" />
     <Compile Include="ExtractDocs.fs" />
     <Compile Include="build.fs" />
   </ItemGroup>