docs: add fsdocs initial impl

.config/dotnet-tools.json

@@ -8,6 +8,13 @@
         "fantomas"
       ],
       "rollForward": false
+    },
+    "fsdocs-tool": {
+      "version": "20.0.1",
+      "commands": [
+        "fsdocs"
+      ],
+      "rollForward": false
     }
   }
 }

.github/workflows/docs.yml

@@ -0,0 +1,46 @@
+name: Docs
+
+# Trigger this Action when new code is pushed to the main branch
+on:
+  push:
+    branches:
+      - main
+
+# We need some permissions to publish to Github Pages
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      # Checkout the source code
+      - uses: actions/checkout@v4
+      # Setup dotnet, please use a global.json to ensure the right SDK is used!
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v3
+      # Restore the local tools
+      - name: Restore tools
+        run: dotnet tool restore
+      # Build the code for the API documentation
+      - name: Build code
+        run: dotnet build -c Release Threads.Lib/Threads.Lib.fsproj
+      # Generate the documentation files
+      - name: Generate the documentation'
+        run: dotnet fsdocs build --properties Configuration=Release
+      # Upload the static files
+      - name: Upload documentation
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./output
+
+  # GitHub Actions recommends deploying in a separate job.
+  deploy:
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -482,3 +482,7 @@ $RECYCLE.BIN/
 
 # Vim temporary swap files
 *.swp
+
+output
+.fsdocs
+tmp

Sample/Profile.fs

@@ -17,7 +17,6 @@ open Navs.Avalonia
 
 open Threads.Lib
 open Threads.Lib.Profiles
-open Threads.Lib
 
 module Profile =
   open System

Sample/Sample.fsproj

@@ -2,6 +2,7 @@
   <PropertyGroup>
     <OutputType>Exe</OutputType>
     <TargetFramework>net8.0</TargetFramework>
+    <GenerateDocumentationFile>false</GenerateDocumentationFile>
   </PropertyGroup>
   <ItemGroup>
     <Compile Include="Extensions.fs" />
@@ -26,4 +27,4 @@
   <ItemGroup>
     <ProjectReference Include="..\Threads.Lib\Threads.Lib.fsproj" />
   </ItemGroup>
-</Project>
+</Project>

Threads.Lib/Threads.Lib.fsproj

@@ -3,6 +3,12 @@
     <TargetFramework>net8.0</TargetFramework>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
   </PropertyGroup>
+  <PropertyGroup>
+    <RepositoryUrl>https://github.com/AngelMunoz/Threads.Lib</RepositoryUrl>
+    <FsDocsLicenseLink>https://github.com/AngelMunoz/Threads.Lib/blob/master/License.md</FsDocsLicenseLink>
+    <FsDocsReleaseNotesLink>https://github.com/AngelMunoz/Threads.Lib/blob/master/RELEASE_NOTES.md</FsDocsReleaseNotesLink>
+    <PackageProjectUrl>https://AngelMunoz.github.io/Threads.Lib</PackageProjectUrl>
+  </PropertyGroup>
   <ItemGroup>
     <Compile Include="Pagination.fsi" />
     <Compile Include="Pagination.fs" />
@@ -25,4 +31,4 @@
     <PackageReference Include="FsToolkit.ErrorHandling.TaskResult" Version="4.16.0" />
     <PackageReference Include="Thoth.Json.Net" Version="12.0.0" />
   </ItemGroup>
-</Project>
+</Project>

Threads.Lib/Threads.fs

@@ -5,8 +5,6 @@ open System.Threading.Tasks
 open FsHttp
 open System.Runtime.InteropServices
 
-open Threads.Lib
-
 type InsightsService =
   abstract FetchMediaInsights:
     mediaId: string *

docs/index.md

@@ -0,0 +1,91 @@
+# Threads.Lib
+
+This is a .NET library for the [Threads] API.
+
+## Installation
+
+WIP
+
+## Usage
+
+The library itself is a thin wrapper over the API, so you don't have to craft everything yourself. However we don't provide any authentication dances, so you have to [obtain the access token] required to interact with the API yourself.
+
+Once you have your access token ready to go you can obtain a client instance like this:
+
+```fsharp
+open Threads.Lib
+open Threads.Lib.Profile
+
+let threads = Threads.Create("access-token")
+
+async {
+  let! (response: ProfileValue seq) =
+    threads.Profile.FetchProfile(
+      profileId = "me",
+      profileFields = [
+        ProfileField.Id
+        ProfileField.Username
+        ProfileField.ThreadsBiography
+        ProfileField.ThreadsProfilePictureUrl
+      ]
+    )
+
+    printfn $"%A{response}"
+}
+```
+
+The Threads API is quite dynamic and you can choose which fields you want to obtain in the response, this is at odds with fsharp's type system which requires types to be statically known at compile time. To work around this we provide a `ProfileValue` type which is a discriminated union of all possible fields you can obtain from the API. This way you can pattern match on the response and extract the fields you need.
+
+An example would be:
+
+```fsharp
+// Define a type to represent the user profile
+// with all of the fields you're interested in
+type UserProfile = {
+    id: string
+    username: string
+    bio: string
+  }
+
+  module UserProfile =
+    let emptyProfile = {
+      id = ""
+      username = ""
+      bio = ""
+    }
+
+    // In a module or static method, you can define a mapping function to convert
+    // the ProfileValue seq to a your type instance
+    let ofValues (values: ProfileValue seq) : UserProfile =
+
+      let foldToProfile (current: UserProfile) (nextValue: ProfileValue) =
+        match nextValue with
+        | Id id -> { current with id = id }
+        | Username username -> { current with username = username }
+        | ThreadsBiography bio -> { current with bio = bio }
+        | ThreadsProfilePictureUrl profilePicture -> current
+
+      Seq.fold foldToProfile emptyProfile values
+
+// somewhere else in your code
+async {
+  let! (response: ProfileValue seq) =
+    threads.Profile.FetchProfile(
+      profileId = "me",
+      profileFields = [
+        ProfileField.Id
+        ProfileField.Username
+        ProfileField.ThreadsBiography
+      ]
+    )
+
+  let profile = UserProfile.ofValues response
+  printfn $"%A{profile}"
+  // { id = "1234"; username = "johndoe"; bio = "I'm a bio" }
+}
+```
+
+While there are too few fields in the profile response. This will come more handy in other responses like the thread posts themselves. Overall the library is meant to be used like this and tries to be as flexible as possible without compromising the type safety of F# or at least that's what we're trying.
+
+[Threads]: https://developers.facebook.com/docs/threads
+[obtain the access token]: https://developers.facebook.com/docs/threads/get-started/get-access-tokens-and-permissions