Use Vitepress to build markdown documentation

.editorconfig

@@ -15,7 +15,7 @@ ij_kotlin_name_count_to_use_star_import = 1000
 ij_kotlin_name_count_to_use_star_import_for_members = 1000
 ij_kotlin_packages_to_use_import_on_demand =
 
-[*.xml]
+[{*.xml,*.json,*.ts}]
 charset = utf-8
 indent_style = tab
 tab_width = 4

.gitignore

@@ -9,3 +9,6 @@ local.properties
 build/
 
 java_*.hprof
+
+# Docs
+node_modules

docs/.vitepress/config.ts

@@ -0,0 +1,69 @@
+import { defineConfig } from 'vitepress';
+
+export default defineConfig({
+	title: 'Jellyfin Kotlin SDK',
+	description: 'Documentation for the Jellyfin Kotlin SDK.',
+
+	themeConfig: {
+		logo: 'jellyfin.svg',
+		siteTitle: 'Kotlin SDK',
+		socialLinks: [
+			{
+				icon: 'github',
+				link: 'https://github.com/jellyfin/jellyfin-sdk-kotlin',
+			}
+		],
+		footer: {
+			message: 'Released under the LGPL-3.0 license.',
+		},
+
+		// Top navigation
+		nav: [
+			{
+				text: 'Guide',
+				link: '/guide/getting-started',
+			},
+			{
+				text: 'Dokka',
+				link: '/dokka/',
+			},
+		],
+
+		// Side navigation
+		sidebar: [
+			{
+				text: 'Introduction',
+				items: [
+					{
+						text: 'Getting started',
+						link: '/guide/getting-started',
+					},
+				]
+			},
+
+			{
+				text: 'Developing',
+				items: [
+					{
+						text: 'WebSockets',
+						link: '/guide/websockets',
+					},
+				]
+			},
+
+			{
+				text: 'Migrations',
+				items: [
+					{
+						text: 'Migrate to 1.2',
+						link: '/migration/v1.1',
+					},
+					{
+						text: 'Migrate to 1.2',
+						link: '/migration/v1.2',
+					},
+				]
+			}
+		],
+	},
+});

docs/guide/getting-started.md

@@ -0,0 +1,171 @@
+# Getting started
+
+The SDK is currently available for the JVM and Android 4.4 and up. Java 8 or higher is required. Android versions below
+Android 8 should use [library desugaring](https://developer.android.com/studio/write/java8-support#library-desugaring).
+
+## Setup
+
+Releases are published to `mavenCentral()`. Make sure to use the correct library depending on your
+platform.
+
+![Latest version on Maven Central](https://img.shields.io/maven-central/v/org.jellyfin.sdk/jellyfin-core.svg)
+
+**Gradle with Kotlin DSL**
+
+```kotlin
+implementation("org.jellyfin.sdk:jellyfin-core:$sdkVersion")
+```
+
+<details>
+  <summary>Gradle with Groovy</summary>
+
+  ```groovy
+  implementation "org.jellyfin.sdk:jellyfin-core:$sdkVersion"
+   ```
+</details>
+
+<details>
+  <summary>Maven</summary>
+
+  ```xml
+  <dependency>
+      <groupId>org.jellyfin.sdk</groupId>
+      <artifactId>jellyfin-core</artifactId>
+      <version>$sdkVersion</version>
+  </dependency>
+   ```
+</details>
+
+<details>
+  <summary>Using SNAPSHOT versions</summary>
+
+When working on new features in your application you might need a build of the SDK targeting the next server version.
+For this use case we publish two SNAPSHOT releases: `master-SNAPSHOT` and `openapi-unstable-SNAPSHOT`. To use the
+snapshot versions, add the snapshot repository to your build script:
+`https://s01.oss.sonatype.org/content/repositories/snapshots/`
+
+An example using Gradle with Kotlin DSL that only allows the `master-SNAPSHOT` version:
+
+  ```kotlin
+  repositories {
+      maven("https://s01.oss.sonatype.org/content/repositories/snapshots/") {
+          content {
+              // Only allow SDK snapshots
+              includeVersionByRegex("org\\.jellyfin\\.sdk", ".*", "master-SNAPSHOT")
+          }
+      }
+  }
+   ```
+</details>
+
+## Usage
+
+### Creating a Jellyfin instance
+
+Most functionality of the SDK requires an instance of the Jellyfin class. This class holds
+the configuration required to make API calls and platform specific options. The Jellyfin class can
+be instantiated using a custom Kotlin DSL:
+
+```kotlin
+val jellyfin = createJellyfin {
+    clientInfo = ClientInfo(name = "My awesome client!", version = "1.33.7",)
+
+    // Uncomment when using android:
+    // context = /* Android Context */
+}
+```
+
+Make sure to supply the client information if you want to make API calls. The context is required for Android
+applications.
+
+### Creating an API instance
+
+API calls require an API instance. This can be done with the createApi function. It requires a
+server address. The client and device information are set automatically but can be changed. All
+properties can be changed later in the API instance.
+
+```kotlin
+val api = jellyfin.createApi(
+    baseUrl = "https://demo.jellyfin.org/stable/",
+    // Optional options:
+    // accessToken = "access token or api key"
+    // clientInfo = ClientInfo(), // defaults to parent info
+    // deviceInfo = DeviceInfo(), // defaults to parent info
+    // httpClientOptions = HttpClientOptions() // allows setting additional options
+)
+```
+
+### Authenticating a user
+
+All API operations are grouped. To make use of an operation you need to first get the group from your ApiClient
+instance. All groups are defined as extension functions, and you can alternatively construct the API instances
+manually.
+
+```kotlin
+val userApi = api.userApi
+
+try {
+    val authenticationResult by userApi.authenticateUserByName(
+        username = "demo", 
+        password = "",
+    )
+    
+    // Use access token in api instance
+    api.accessToken = authenticationResult.accessToken
+    
+    // Print session information
+    println(authenticationResult.sessionInfo)
+} catch(err: ApiClientException) {
+    // Catch exceptions
+    println("Something went wrong! ${err.message}")
+}
+```
+
+### WebSockets
+
+Jellyfin uses WebSockets to communicate events like library changes and activities. This API can be
+used with the SocketApi. Documentation is available in the [docs](/docs) folder.
+
+```kotlin
+val instance = api.ws()
+
+instance.addGlobalListener { message ->
+	println(message)
+}
+```
+
+### Server discovery
+
+The server discovery feature can be used to find servers on the local network, normalize inputted
+server addresses and to determine the best server to use from a list of addresses.
+
+```kotlin
+// Discover servers on the local network
+jellyfin.discovery.discoverLocalServers().collect {
+    println("Server ${it.name} was found at address ${it.address}")
+}
+
+// Get all candidates for a given input
+val candidates = jellyfin.discovery.getAddressCandidates("demo.jellyfin.org/stable")
+
+// Get a flow of potential servers to connect to
+val recommended = jellyfin.discovery.getRecommendedServers(candidates, RecommendedServerInfoScore.GOOD)
+```
+
+## More examples
+
+We provide a few small projects in the [samples](/samples) folder. The samples are used for testing
+new features and can be used as a basis for your own application.
+
+## Projects using the SDK
+
+### Official Jellyfin clients
+
+- [Jellyfin for Android](https://github.com/jellyfin/jellyfin-android) is the official Android client for phones and tablets.
+- [Jellyfin for Android TV](https://github.com/jellyfin/jellyfin-androidtv) is the official Android TV client for Android TV, Nvidia Shield, Amazon Fire TV and Google TV.
+
+### Third party clients
+
+- [Findroid](https://github.com/jarnedemeulemeester/findroid) provides a native user interface to browse and play movies and series.
+
+_Want to add your project? We'd love to know about it, open an issue or create pull request!_

docs/index.md

@@ -0,0 +1,17 @@
+---
+layout: home
+
+hero:
+  name: Jellyfin Kotlin SDK
+  tagline: The Jellyfin Kotlin SDK is a library implementing the Jellyfin API to easily access servers.
+  image:
+    src: jellyfin.svg
+    alt: Jellyfin logo
+  actions:
+    - theme: brand
+      text: Get started
+      link: /guide/getting-started
+    - theme: alt
+      text: View on GitHub
+      link: https://github.com/jellyfin/jellyfin-sdk-kotlin
+---

docs/public/jellyfin.svg

@@ -0,0 +1,34 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- ***** BEGIN LICENSE BLOCK *****
+  - Part of the Jellyfin project (https://jellyfin.media)
+  - 
+  - All copyright belongs to the Jellyfin contributors; a full list can
+  - be found in the file CONTRIBUTORS.md
+  - 
+  - This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License.
+  - To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/4.0/.
+- ***** END LICENSE BLOCK ***** -->
+<svg id="banner-dark" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 1536 512">
+    <defs>
+        <linearGradient id="linear-gradient" x1="110.25" y1="213.3" x2="496.14" y2="436.09" gradientUnits="userSpaceOnUse">
+            <stop offset="0" stop-color="#aa5cc3"/>
+            <stop offset="1" stop-color="#00a4dc"/>
+        </linearGradient>
+    </defs>
+    <title>banner-dark</title>
+    <g id="banner-dark">
+        <g id="banner-dark-icon">
+            <path id="inner-shape" d="M261.42,201.62c-20.44,0-86.24,119.29-76.2,139.43s142.48,19.92,152.4,0S281.86,201.63,261.42,201.62Z" fill="url(#linear-gradient)"/>
+            <path id="outer-shape" d="M261.42,23.3C199.83,23.3,1.57,382.73,31.8,443.43s429.34,60,459.24,0S323,23.3,261.42,23.3ZM411.9,390.76c-19.59,39.33-281.08,39.77-300.9,0S221.1,115.48,261.45,115.48,431.49,351.42,411.9,390.76Z" fill="url(#linear-gradient)"/>
+        </g>
+        <g id="jellyfin-light-outlines" style="isolation:isolate" transform="translate(43.8)">
+            <path d="M556.64,350.75a67,67,0,0,1-22.87-27.47,8.91,8.91,0,0,1-1.49-4.75,7.42,7.42,0,0,1,2.83-5.94,9.25,9.25,0,0,1,6.09-2.38c3.16,0,5.94,1.69,8.31,5.05a48.09,48.09,0,0,0,16.34,20.34,40.59,40.59,0,0,0,24,7.58q20.51,0,33.27-12.62t12.77-33.12V159a8.44,8.44,0,0,1,2.67-6.39,9.56,9.56,0,0,1,6.83-2.52,9,9,0,0,1,6.68,2.52,8.7,8.7,0,0,1,2.53,6.39v138.4a64.7,64.7,0,0,1-8.32,32.67,59,59,0,0,1-23,22.72Q608.62,361,589.9,361A57.21,57.21,0,0,1,556.64,350.75Z" fill="#fff"/>
+            <path d="M831.66,279.47a8.77,8.77,0,0,1-6.24,2.53H713.16q0,17.82,7.27,31.92a54.91,54.91,0,0,0,20.79,22.28q13.51,8.18,31.93,8.17a54,54,0,0,0,25.54-5.94,52.7,52.7,0,0,0,18.12-15.15,10,10,0,0,1,6.24-2.67,8.14,8.14,0,0,1,7.72,7.72,8.81,8.81,0,0,1-3,6.24,74.7,74.7,0,0,1-23.91,19A65.56,65.56,0,0,1,773.45,361q-22.87,0-40.4-9.8a69.51,69.51,0,0,1-27.32-27.48q-9.79-17.66-9.8-40.83,0-24.36,9.65-42.62t25.69-27.92a65.2,65.2,0,0,1,34.16-9.65A70,70,0,0,1,798.84,211a65.78,65.78,0,0,1,25.39,24.36q9.81,16,10.1,38A8.07,8.07,0,0,1,831.66,279.47ZM733.5,231.8Q718.8,243.68,714.64,266H815.92v-2.38A46.91,46.91,0,0,0,807,240.27a48.47,48.47,0,0,0-18.56-15.15,54,54,0,0,0-23-5.2Q748.2,219.92,733.5,231.8Z" fill="#fff"/>
+            <path d="M888.24,355.5a8.92,8.92,0,0,1-15.3-6.38v-202a8.91,8.91,0,1,1,17.82,0v202A8.65,8.65,0,0,1,888.24,355.5Z" fill="#fff"/>
+            <path d="M956.55,355.5a8.92,8.92,0,0,1-15.3-6.38v-202a8.91,8.91,0,1,1,17.82,0v202A8.65,8.65,0,0,1,956.55,355.5Z" fill="#fff"/>
+            <path d="M1122.86,206.11a8.7,8.7,0,0,1,2.53,6.39v131q0,23.44-9.21,40.09a61.58,61.58,0,0,1-25.54,25.25q-16.34,8.61-36.83,8.61a96.73,96.73,0,0,1-23.31-2.68,61.72,61.72,0,0,1-18-7.12q-6.24-3.87-6.24-8.62a17.94,17.94,0,0,1,.6-3,8.06,8.06,0,0,1,3-4.45,7.49,7.49,0,0,1,4.45-1.49,7.91,7.91,0,0,1,3.56.89q19,10.39,36.24,10.4,24.65,0,39.06-15.44t14.4-42.18V333.38a54.37,54.37,0,0,1-21.38,20,62.55,62.55,0,0,1-30.3,7.58q-25.83,0-39.2-15.45t-13.37-41.87V212.5a8.91,8.91,0,1,1,17.82,0V301q0,21.39,9.36,32.38t29.25,11a48,48,0,0,0,23.32-6.09,49.88,49.88,0,0,0,17.82-16,37.44,37.44,0,0,0,6.68-21.24V212.5a9,9,0,0,1,15.29-6.39Z" fill="#fff"/>
+            <path d="M1210.18,161.41q-5.21,6.24-5.2,17.23v30.59h33.27a8.19,8.19,0,0,1,5.79,2.38,8.26,8.26,0,0,1,0,11.88,8.22,8.22,0,0,1-5.79,2.37H1205V349.12a8.91,8.91,0,1,1-17.82,0V225.86h-21.68a7.83,7.83,0,0,1-5.94-2.52,8.21,8.21,0,0,1-2.37-5.79,8,8,0,0,1,2.37-6.09,8.33,8.33,0,0,1,5.94-2.23h21.68V178.64q0-18.7,10.84-29t29-10.24a46.1,46.1,0,0,1,15.45,2.52q7.13,2.53,7.12,8.17a8.07,8.07,0,0,1-2.37,5.94,7.37,7.37,0,0,1-5.35,2.37,18.81,18.81,0,0,1-6.53-1.48,42,42,0,0,0-10.4-1.78Q1215.37,155.18,1210.18,161.41ZM1276,180.87c-2.19-1.88-3.27-4.61-3.27-8.17v-3q0-5.34,3.41-8.17t9.36-2.82q11.88,0,11.88,11v3c0,3.56-1,6.29-3.12,8.17s-5.1,2.82-9.06,2.82S1278.14,182.75,1276,180.87Zm15.59,174.63a8.92,8.92,0,0,1-15.3-6.38V212.5a8.91,8.91,0,1,1,17.82,0V349.12A8.65,8.65,0,0,1,1291.56,355.5Z" fill="#fff"/>
+            <path d="M1452.53,218.88q12.92,16.2,12.92,42.92v87.32a8.4,8.4,0,0,1-2.67,6.38,8.8,8.8,0,0,1-6.24,2.53,8.64,8.64,0,0,1-8.91-8.91V262.69q0-19.31-9.65-31.33t-29.85-12a53.28,53.28,0,0,0-42.77,21.83,36.24,36.24,0,0,0-7.13,21.53v86.43a8.91,8.91,0,1,1-17.82,0V216.06a8.91,8.91,0,1,1,17.82,0V232.4q8-12.77,23-21.24A61.84,61.84,0,0,1,1412,202.7Q1439.61,202.7,1452.53,218.88Z" fill="#fff"/>
+        </g>
+    </g>
+</svg>

package.json

@@ -0,0 +1,10 @@
+{
+	"description": "This file is used for the documentation only",
+	"scripts": {
+		"start": "vitepress dev docs",
+		"build": "vitepress build docs"
+	},
+	"devDependencies": {
+		"vitepress": "1.0.0-alpha.12"
+	}
+}