Fix docfx source files (#3453)

realm · Oct 2, 2023 · 15b1e1a · 15b1e1a
1 parent 1d26dff
commit 15b1e1a
Show file tree

Hide file tree

Showing 4 changed files with 40 additions and 4 deletions.
diff --git a/.github/templates/build-packages.yml b/.github/templates/build-packages.yml
@@ -8,20 +8,40 @@
     uses: #@ actionCache
     with:
       path: 'C:\docfx'
-      key: docfx-2.62.1
+      key: docfx-2.70.4
   - name: Download docfx
     if: inputs.build-docs && steps.check-docfx-cache.outputs.cache-hit != 'true'
     run: |
-      Invoke-WebRequest -Uri https://github.com/dotnet/docfx/releases/download/v2.62.1/docfx-win-x64-v2.62.1.zip -OutFile C:\docfx.zip
+      Invoke-WebRequest -Uri https://github.com/dotnet/docfx/releases/download/v2.70.4/docfx-win-x64-v2.70.4.zip -OutFile C:\docfx.zip
       Expand-Archive -Path C:\docfx.zip -DestinationPath C:\docfx
     shell: powershell
   - _: #@ template.replace(setupDotnet("6.0.402", ifCondition = "inputs.build-docs"))
   - name: Build docs
     if: inputs.build-docs
+    env:
+      DOCFX_SOURCE_BRANCH_NAME: ${{ github.head_ref }}
     run: |
       New-Item global.json
       Set-Content global.json '{ "sdk": { "version": "6.0.402" } }'
       C:\docfx\docfx Docs/docfx.json
+
+#! the link generated by docfx is incorrect - it points to
+#! https://github.com/realm/realm-dotnet/new/main/Docs/apispec/new?filename=...
+#! instead of
+#! https://github.com/realm/realm-dotnet/new/main/Docs/apispec?filename=...
+  - name: Update Improve this doc links
+    run: |
+      Get-ChildItem Docs/_site -Filter *.html -Recurse -File |
+      ForEach-Object {
+          $content = ($_ | Get-Content -Raw)
+          $content = $content -replace "/Docs/apispec/new\?filename", "/Docs/apispec?filename"
+          Set-Content $_.FullName $content
+      }
+    shell: pwsh
+
+  - name: Archive docs
+    if: inputs.build-docs
+    run: |
       Compress-Archive -Path Docs/_site -DestinationPath "Realm/packages/Docs.zip"
   - _: #@ template.replace(uploadArtifacts("Docs.zip", "Realm/packages/Docs.zip"))
     if: inputs.build-docs

diff --git a/.github/workflows/build-packages.yml b/.github/workflows/build-packages.yml
@@ -224,10 +224,24 @@ jobs:
         dotnet-version: 6.0.402
     - name: Build docs
       if: inputs.build-docs
+      env:
+        DOCFX_SOURCE_BRANCH_NAME: ${{ github.head_ref }}
       run: |
         New-Item global.json
         Set-Content global.json '{ "sdk": { "version": "6.0.402" } }'
         C:\docfx\docfx Docs/docfx.json
+    - name: Update Improve this doc links
+      run: |
+        Get-ChildItem Docs/_site -Filter *.html -Recurse -File |
+        ForEach-Object {
+            $content = ($_ | Get-Content -Raw)
+            $content = $content -replace "/Docs/apispec/new\?filename", "/Docs/apispec?filename"
+            Set-Content $_.FullName $content
+        }
+      shell: pwsh
+    - name: Archive docs
+      if: inputs.build-docs
+      run: |
         Compress-Archive -Path Docs/_site -DestinationPath "Realm/packages/Docs.zip"
     - name: Store artifacts for Docs.zip
       uses: actions/upload-artifact@v3

diff --git a/Docs/docfx.json b/Docs/docfx.json
@@ -18,7 +18,8 @@
             "filter": "filterConfig.yml",
             "properties": {
                 "TargetFramework": "netstandard2.0"
-            }
+            },
+            "EnumSortOrder": "declaringOrder"
         }
     ],
     "build": {
@@ -82,7 +83,7 @@
             "_gitContribute": {
                 "repo": "https://github.com/realm/realm-dotnet.git",
                 "branch": "main",
-                "path": "Docs/apispec"
+                "apiSpecFolder": "Docs/apispec"
             }
         },
         "fileMetadataFiles": [],

diff --git a/Realm/Realm.PlatformHelpers/Realm.PlatformHelpers.csproj b/Realm/Realm.PlatformHelpers/Realm.PlatformHelpers.csproj
@@ -22,6 +22,7 @@
     <LangVersion>9.0</LangVersion>
     <nullable>enable</nullable>
     <AndroidResgenNamespace>Realms.PlatformHelpers</AndroidResgenNamespace>
+    <NoWarn>NETSDK1202</NoWarn>
   </PropertyGroup>
 
   <ItemGroup>