Merge pull request #850 from Romfos/main

Migrate documentation to docfx
nsubstitute · Dec 15, 2024 · d0ff096 · d0ff096
2 parents dfef728 + 04d33fd
commit d0ff096
Show file tree

Hide file tree

Showing 79 changed files with 173 additions and 677 deletions.
diff --git a/.github/workflows/release_documentation.yml b/.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
diff --git a/.github/workflows/test.yml b/.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

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,7 @@
 * [UPDATE] Remove legacy obsolete API
 * [UPDATE] Mark as obsolete api CompatArg with pre c# 7.0 support
 * [NEW] Added .NET 9 to test matrix
+* [UPDATE] Migrate documentation to docfx platform. https://github.com/dotnet/docfx
 
 ### 5.3.0 (October 2024)
 

diff --git a/NSubstitute.sln b/NSubstitute.sln
@@ -10,9 +10,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "tests", "tests", "{0E2B9095
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "build", "build", "{A8AF7D01-6CE4-47B2-9E23-689A53991C3D}"
 	ProjectSection(SolutionItems) = preProject
-		build\build.cmd = build\build.cmd
 		build\build.fs = build\build.fs
-		build\build.sh = build\build.sh
 		build\ExtractDocs.fs = build\ExtractDocs.fs
 	EndProjectSection
 EndProject

diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 NSubstitute
 ========
-[![Build status](https://github.com/nsubstitute/NSubstitute/actions/workflows/build_and_test.yml/badge.svg)](https://github.com/nsubstitute/NSubstitute/actions/workflows/build_and_test.yml)
+[![Build, Test, and Format verification](https://github.com/nsubstitute/NSubstitute/actions/workflows/test.yml/badge.svg)](https://github.com/nsubstitute/NSubstitute/actions/workflows/test.yml)
 [![Nuget](https://img.shields.io/nuget/v/NSubstitute.svg)](https://www.nuget.org/packages/NSubstitute)
 
 Visit the [NSubstitute website](https://nsubstitute.github.io) for more information.

diff --git a/build/build.cmd b/build/build.cmd
diff --git a/build/build.fs b/build/build.fs
@@ -1,19 +1,13 @@
-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
 open Fake.IO.FileSystemOperators
 
 open ExtractDocs
 
-let target = Target.create
-let description = Target.description
-
 module FileReaderWriter =
     let Read file = File.ReadAllText(file)
     let Write file (text: string) = File.WriteAllText(file, text)
@@ -39,97 +33,39 @@ module ExamplesToCode =
             for file in files do
                 ConvertFile file targetDir
 
-type BuildVersion = { assembly: string; file: string; info: string; package: string }
 
 let root = __SOURCE_DIRECTORY__ </> ".." |> Path.getFullName
 
 let configuration = Environment.environVarOrDefault "configuration" "Debug"
 
 let output = root </> "bin" </> configuration
-let solution = (root </> "NSubstitute.sln")
-
-let initTargets() =
-    Target.description("Extract, build and test code from documentation.")
-    Target.create "TestCodeFromDocs" <| fun _ ->
-        let outputCodePath = output </> "CodeFromDocs"
-        Directory.create outputCodePath
-        // generate samples from docs
-        ExamplesToCode.Convert [ root </> "docs/"; root </> "docs/help/_posts/"; root ] outputCodePath
-        // compile code samples
-        let csproj = """
-            <Project Sdk="Microsoft.NET.Sdk">
-            <PropertyGroup>
-                <TargetFrameworks>net8.0;net462</TargetFrameworks>
-                <LangVersion>latest</LangVersion>
-            </PropertyGroup>
-            <ItemGroup>
-                <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.12.0" />
-                <PackageReference Include="NUnit" Version="3.14.0" />
-                <PackageReference Include="NUnit3TestAdapter" Version="4.6.0" />
-            </ItemGroup>
-            <ItemGroup>
-                <ProjectReference Include="..\..\..\src\NSubstitute\NSubstitute.csproj" />
-            </ItemGroup>
-        </Project>
-        """
-        let projPath = outputCodePath </> "Docs.csproj"
-        FileReaderWriter.Write projPath csproj
-        DotNet.restore (fun p -> p) projPath
-        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:"
-        printfn "  configuration=Debug|Release"
-        printfn "  benchmark=*|<benchmark name>  (only for Benchmarks target in Release mode)"
-        printfn ""
-        Target.listAvailable()
-
-    "Documentation" <== [ "TestCodeFromDocs" ]
 
 [<EntryPoint>]
 let main argv =
-    argv
-    |> Array.toList
-    |> Context.FakeExecutionContext.Create false "build.fsx"
-    |> Context.RuntimeContext.Fake
-    |> Context.setExecutionContext
-    initTargets()
-    Target.runOrDefaultWithArguments "TestCodeFromDocs"
-    0 
+    let outputCodePath = output </> "CodeFromDocs"
+    Directory.create outputCodePath
+    // generate samples from docs
+    ExamplesToCode.Convert [ root </> "docs/"; root </> "docs/docs"; root ] outputCodePath
+    // compile code samples
+    let csproj = """
+        <Project Sdk="Microsoft.NET.Sdk">
+        <PropertyGroup>
+            <TargetFrameworks>net8.0;net462</TargetFrameworks>
+            <LangVersion>latest</LangVersion>
+        </PropertyGroup>
+        <ItemGroup>
+            <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.12.0" />
+            <PackageReference Include="NUnit" Version="3.14.0" />
+            <PackageReference Include="NUnit3TestAdapter" Version="4.6.0" />
+        </ItemGroup>
+        <ItemGroup>
+            <ProjectReference Include="..\..\..\src\NSubstitute\NSubstitute.csproj" />
+        </ItemGroup>
+    </Project>
+    """
+    let projPath = outputCodePath </> "Docs.csproj"
+    FileReaderWriter.Write projPath csproj
+    DotNet.restore (fun p -> p) projPath
+    DotNet.build (fun p -> p) projPath
+    DotNet.test (fun p -> p) projPath
+    0
diff --git a/build/build.fsproj b/build/build.fsproj
@@ -7,18 +7,14 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <None Include="build.cmd" />
-    <None Include="build.sh" />
     <Compile Include="ExtractDocs.fs" />
     <Compile Include="build.fs" />
   </ItemGroup>
 
   <ItemGroup>
     <PackageReference Include="Microsoft.Build" Version="17.12.6" />
-    <PackageReference Include="Microsoft.Build.Utilities.Core" Version="17.12.6" />
     <PackageReference Include="MSBuild.StructuredLogger" Version="2.2.386" />
     <PackageReference Include="Fake.DotNet.Cli" Version="6.1.3" />
-    <PackageReference Include="Fake.Core.Target" Version="6.1.3" />
   </ItemGroup>
 
 </Project>
diff --git a/build/build.sh b/build/build.sh
diff --git a/docs/_config.yml b/docs/_config.yml
diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html
diff --git a/docs/_layouts/post.html b/docs/_layouts/post.html
diff --git a/docs/_plugins/kramdownplus.rb b/docs/_plugins/kramdownplus.rb