update docs to latest fsdocs with ipynb input

nfdi4plants · Jan 3, 2024 · 062ee63 · 062ee63
1 parent 2d0ccc6
commit 062ee63
Show file tree

Hide file tree

Showing 27 changed files with 414 additions and 533 deletions.
diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json
@@ -3,15 +3,15 @@
   "isRoot": true,
   "tools": {
     "fsdocs-tool": {
-      "version": "18.1.1",
+      "version": "20.0.0-alpha-016",
       "commands": [
         "fsdocs"
       ]
     },
-    "docfx": {
-      "version": "2.70.1",
+    "dotnet-repl": {
+      "version": "0.1.208",
       "commands": [
-        "docfx"
+        "dotnet-repl"
       ]
     }
   }

diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml
@@ -13,16 +13,12 @@ jobs:
     steps:
     - name: Checkout
       uses: actions/checkout@v3
-    - name: Setup .NET 6.0
+    - name: Setup .NET 8.0
       uses: actions/setup-dotnet@v3
       with:
-        dotnet-version: '6.0.x'
+        dotnet-version: '8.0.x'
     - name: Restore tools
       run: dotnet tool restore
-    - name: setup-conda
-      uses: s-weigand/[email protected]
-    - name: install nbconvert
-      run: conda install nbconvert -y
     - name: make script executable
       run: chmod u+x build.sh
     - name: Build docs

diff --git a/.gitignore b/.gitignore
@@ -352,3 +352,4 @@ MigrationBackup/
 /tests/ArcGraphModel.JsNativeTests/fable/**/*.js.map
 /.fsdocs
 /tmp/watch
+/output
diff --git a/ARCTokenization.sln b/ARCTokenization.sln
@@ -40,35 +40,21 @@ EndProject
 Project("{6EC3EE1D-3C4E-46DD-8F32-0CC8E7565705}") = "ARCTokenization.Tests", "tests\ARCTokenization.Tests\ARCTokenization.Tests.fsproj", "{30177EF1-3980-4FFE-9B49-90B75DCEBDA3}"
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{551D4715-5ECD-4CAB-8A4A-41E246F4A7B5}"
-EndProject
-Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docfx_project", "docfx_project", "{86CD7F81-ADB4-4991-A960-063FE02D907D}"
 	ProjectSection(SolutionItems) = preProject
-		docs\docfx_project\.gitignore = docs\docfx_project\.gitignore
-		docs\convert-notebook.ps1 = docs\convert-notebook.ps1
-		docs\convert-notebooks.ps1 = docs\convert-notebooks.ps1
-		docs\docfx_project\docfx.json = docs\docfx_project\docfx.json
-		docs\docfx_project\index.md = docs\docfx_project\index.md
-		docs\docfx_project\toc.yml = docs\docfx_project\toc.yml
+		docs\index.ipynb = docs\index.ipynb
 	EndProjectSection
 EndProject
-Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "ARCTokenization", "ARCTokenization", "{E669BA6D-4327-40AE-8CE1-E6FEA8F89A15}"
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "ARCTokenization", "ARCTokenization", "{699C5B9A-EA4B-4D25-B05D-16CA14320CFB}"
 	ProjectSection(SolutionItems) = preProject
-		docs\docfx_project\ARCTokenization\intro.md = docs\docfx_project\ARCTokenization\intro.md
+		docs\ARCTokenization\Introduction.ipynb = docs\ARCTokenization\Introduction.ipynb
 	EndProjectSection
 EndProject
-Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "ControlledVocabulary", "ControlledVocabulary", "{F6471491-8FE4-48A7-BA9E-1113DE63B5F5}"
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "ControlledVocabulary", "ControlledVocabulary", "{524F5156-C079-4AEF-822E-F01DAE6874AA}"
 	ProjectSection(SolutionItems) = preProject
-		docs\docfx_project\ControlledVocabulary\CvParam.ipynb = docs\docfx_project\ControlledVocabulary\CvParam.ipynb
-		docs\docfx_project\ControlledVocabulary\intro.ipynb = docs\docfx_project\ControlledVocabulary\intro.ipynb
+		docs\ControlledVocabulary\CvParam.ipynb = docs\ControlledVocabulary\CvParam.ipynb
+		docs\ControlledVocabulary\Introduction.ipynb = docs\ControlledVocabulary\Introduction.ipynb
 	EndProjectSection
 EndProject
-Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "api", "api", "{9031C346-A994-4943-AB58-1095882E725C}"
-	ProjectSection(SolutionItems) = preProject
-		docs\docfx_project\api\index.md = docs\docfx_project\api\index.md
-	EndProjectSection
-EndProject
-Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "images", "images", "{31DCBC4B-41D9-4CE1-9E5D-3F5A3F5E01CA}"
-EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -105,11 +91,8 @@ Global
 		{ED24D0E3-BA79-4F6D-9A30-D05FF4EBAFDB} = {3DB2A5F4-23F6-4A06-9AE5-CEAC0707735B}
 		{24D99DC2-DF18-45A3-B444-B60351F131DB} = {67DA0DCC-75F4-4F30-91C3-309A48B13D49}
 		{30177EF1-3980-4FFE-9B49-90B75DCEBDA3} = {2EB71559-9BE4-4E02-9763-9092876D1E4A}
-		{86CD7F81-ADB4-4991-A960-063FE02D907D} = {551D4715-5ECD-4CAB-8A4A-41E246F4A7B5}
-		{E669BA6D-4327-40AE-8CE1-E6FEA8F89A15} = {86CD7F81-ADB4-4991-A960-063FE02D907D}
-		{F6471491-8FE4-48A7-BA9E-1113DE63B5F5} = {86CD7F81-ADB4-4991-A960-063FE02D907D}
-		{9031C346-A994-4943-AB58-1095882E725C} = {86CD7F81-ADB4-4991-A960-063FE02D907D}
-		{31DCBC4B-41D9-4CE1-9E5D-3F5A3F5E01CA} = {86CD7F81-ADB4-4991-A960-063FE02D907D}
+		{699C5B9A-EA4B-4D25-B05D-16CA14320CFB} = {551D4715-5ECD-4CAB-8A4A-41E246F4A7B5}
+		{524F5156-C079-4AEF-822E-F01DAE6874AA} = {551D4715-5ECD-4CAB-8A4A-41E246F4A7B5}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {933E3470-7D09-4F22-A056-2407458B9600}

diff --git a/build/DocumentationTasks.fs b/build/DocumentationTasks.fs
@@ -5,33 +5,47 @@ open ProjectInfo
 open BasicTasks
 
 open BlackFox.Fake
-open System.IO
-open Fake.Core
-open Fake.IO
-
-let notebooks =  Directory.EnumerateFiles("docs", "*.ipynb", SearchOption.AllDirectories)
-
-let preprocessNotebooks =
-    BuildTask.create "PreprocessNotebooks" [ ] {
-        notebooks
-        |> Seq.iter (fun nb -> 
-            let dir = Path.GetDirectoryName nb
-            let file = Path.GetFileName nb
-            CreateProcess.fromRawCommandLine "jupyter" $"nbconvert {nb} --to markdown --output-dir={dir}"
-            |> Proc.run // start with the above configuration
-            |> ignore // ignore exit code
-            File.ReadAllText(nb.Replace(".ipynb", ".md"))
-            |> String.replace "polyglot-notebook" "fsharp"
-            |> fun p -> File.WriteAllText(nb.Replace(".ipynb", ".md"), p)
-        )
-    }
 
 let buildDocs =
-    BuildTask.create "BuildDocs" [ build; preprocessNotebooks ] {
-        runDotNet "docfx docs/docfx_project/docfx.json" "./"
+    BuildTask.create "BuildDocs" [ build ] {
+        printfn "building docs with stable version %s" stableDocsVersionTag
+
+        runDotNet
+            (sprintf
+                "fsdocs build --eval --clean --properties Configuration=Release --parameters fsdocs-package-version %s"
+                stableDocsVersionTag)
+            "./"
+    }
+
+let buildDocsPrerelease =
+    BuildTask.create "BuildDocsPrerelease" [ setPrereleaseTag; build ] {
+        printfn "building docs with prerelease version %s" prereleaseTag
+
+        runDotNet
+            (sprintf
+                "fsdocs build --eval --clean --properties Configuration=Release --parameters fsdocs-package-version %s"
+                prereleaseTag)
+            "./"
     }
 
 let watchDocs =
-    BuildTask.create "WatchDocs" [ build; preprocessNotebooks ] {
-        runDotNet "docfx docs/docfx_project/docfx.json --serve" "./"
-    }
+    BuildTask.create "WatchDocs" [ build ] {
+        printfn "watching docs with stable version %s" stableDocsVersionTag
+
+        runDotNet
+            (sprintf
+                "fsdocs watch --eval --clean --properties Configuration=Release --parameters fsdocs-package-version %s"
+                stableDocsVersionTag)
+            "./"
+    }
+
+let watchDocsPrerelease =
+    BuildTask.create "WatchDocsPrerelease" [ setPrereleaseTag; build ] {
+        printfn "watching docs with prerelease version %s" prereleaseTag
+
+        runDotNet
+            (sprintf
+                "fsdocs watch --eval --clean --properties Configuration=Release --parameters fsdocs-package-version %s"
+                prereleaseTag)
+            "./"
+    }
diff --git a/docs/ARCTokenization/Introduction.ipynb b/docs/ARCTokenization/Introduction.ipynb
@@ -0,0 +1,59 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "dotnet_repl_cellExecutionStartTime": "2024-01-03T14:01:31.5046702+01:00",
+    "dotnet_repl_cellExecutionEndTime": "2024-01-03T14:01:31.5267655+01:00"
+   },
+   "source": [
+    "---\n",
+    "\n",
+    "title: Introduction\n",
+    "\n",
+    "category: ARCTokenization\n",
+    "\n",
+    "categoryindex: 2\n",
+    "\n",
+    "index: 1\n",
+    "\n",
+    "---\n",
+    "\n",
+    "# ARCTokenization\n",
+    "\n"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": ".NET (F#)",
+   "language": "F#",
+   "name": ".net-fsharp"
+  },
+  "language_info": {
+   "file_extension": ".fs",
+   "mimetype": "text/x-fsharp",
+   "name": "F#",
+   "pygments_lexer": "fsharp",
+   "version": "6.0"
+  },
+  "polyglot_notebook": {
+   "defaultKernelName": "fsharp",
+   "items": [
+    {
+     "name": "fsharp"
+    }
+   ]
+  },
+  "dotnet_interactive": {
+   "defaultKernelName": "fsharp",
+   "items": [
+    {
+     "name": "fsharp"
+    }
+   ]
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}