Merge pull request #18 from bluefireoly/guide

Add mkdocs guide

guide/docs/index.md

@@ -0,0 +1,9 @@
+# KSpigot
+
+KSpigot extends Spigot (and all of its forks) with additional functionality. This reaches from small extension functions, to features making use of Kotlin's language and finally to bigger APIs (e.g. the GUI API).
+
+KSpigot is [at home on GitHub](https://github.com/bluefireoly/KSpigot). Feel free to contribute to the project.
+
+## Setup
+
+In order to get started, follow the [setup guide](setup/gradle.md).

guide/docs/setup/beginners.md

@@ -0,0 +1,17 @@
+# For absolute beginners
+
+There are several things required to get started with KSpigot.
+
+## Kotlin
+
+Kotlin is requirement for using KSpigot, as it is made for use with the Kotlin programming language.
+
+You can start learning Kotlin with [the official docs](https://kotlinlang.org/docs/home.html) or by using the [Kotlin Playground](https://play.kotlinlang.org/byExample/overview).
+
+## Gradle
+
+You should be able to use Gradle as your build system, although you do not have to understand to much of it. Probably it will even work if you just copy and paste the snippets this guide provides.
+
+## Spigot
+
+Spigot is just an API, meaning that if you are able to use Kotlin, you will be able to use an API like Spigot and KSpigot. Nevertheless, it is good to know at least something about the Spigot API.

guide/docs/setup/entrypoint.md

@@ -0,0 +1,49 @@
+The entrypoint in KSpigot is a class which represents the main class of your plugin.
+
+???+ warning "Type of the main class"
+    Please note that due to a limitation of Spigot, your main class has to be a `class`, it cannot be an `object` or anything else.
+
+## Create the main class
+
+Create a new file at `src/main/kotlin/your/package/structure/` and call it (for example) `Manager`.
+
+Add the following class to the file:
+
+```kotlin
+class InternalMainClass : KSpigot() {
+    override fun load() { }
+    override fun startup() { }
+    override fun shutdown() { }
+}
+```
+
+??? info "Coming from spigot?"
+    When using KSpigot **do not inherit from `JavaPlugin`**, inherit from `KSpigot` instead.
+
+    Also, please note that:
+    
+    - `onLoad` becomes `load`
+    - `onEnable` becomes `startup`
+    - `onDisable` becomes `shutdown`
+
+### Make it globally available
+
+As noted above you cannot use `object` for the main class. Fortunately, due to the fact that there should always only exist one instance of your main class, you can provide it globally by building the main class as follows:
+
+```kotlin
+class InternalMainClass : KSpigot() {
+    companion object {
+        lateinit var INSTANCE: InternalMainClass; private set
+    }
+
+    override fun load() {
+        INSTANCE = this
+    }
+
+    override fun startup() { }
+    
+    override fun shutdown() { }
+}
+
+val Manager by lazy { InternalMainClass.INSTANCE }
+```

guide/docs/setup/gradle.md

@@ -0,0 +1,129 @@
+The following code snippets can be used in your `build.gradle.kts` file.
+
+## Gradle configuration
+
+### Java version
+
+Configuring the Java version is nothing specific to KSpigot, it should always be done. It is listed in this guide anyways, because a lot of beginners forget to do this - and then get confused about not being able to use inline functions.
+
+```kotlin
+val javaVersion = 8 // change this to your Java version
+
+tasks.compileJava {
+    options.release.set(javaVersion)
+}
+
+tasks.compileKotlin {
+    kotlinOptions.jvmTarget = if (javaVersion < 9) "1.$javaVersion" else "$javaVersion"
+}
+```
+
+## Add the Spigot dependency
+
+You have two options:
+
+- **A** add just the Spigot API, if you wish to have a stable API which is built for users
+- **B** use the regular Spigot dependency which contains the whole Minecraft server code (often called "nms" (net.minecraft.server)), as well as the underlying CraftBukkit code - this option gives you a lot more possibilities, but it can also be dangerous
+
+### **A** Just the Spigot API
+
+KSpigot is an extension for Spigot, you still need the regular Spigot dependency.
+
+Add the Spigot Maven repository to your `repositories` scope:
+
+```kotlin
+repositories {
+    maven("https://hub.spigotmc.org/nexus/content/repositories/snapshots")
+}
+```
+
+Add the Spigot API dependency to your `dependencies` scope:
+
+```kotlin
+dependencies {
+    compileOnly("org.spigotmc:spigot-api:1.16.5-R0.1-SNAPSHOT")
+}
+```
+
+Replace the given version at the end of the dependency notation with the version you want to use. [See all versions](https://hub.spigotmc.org/nexus/content/repositories/snapshots/org/spigotmc/spigot-api/) in the Spigot Maven repository.
+
+### **B** The regular Spigot dependency
+
+Download the [BuildTools](https://hub.spigotmc.org/jenkins/job/BuildTools/) to a separate directory, navigate to this directory using your terminal and run `java -jar BuildTools.jar` in order to generate the .jar file of the Spigot server. This file will be installed to your Maven Local repository automatically, so you can add it as dependency to your project. Additionally, you can copy it to anywhere else and use it to create a server. (More information can be found in the [Spigot Wiki](https://www.spigotmc.org/wiki/buildtools/))
+
+Add your Maven Local repository to your `repositories` scope:
+
+```kotlin
+repositories {
+    mavenLocal()
+}
+```
+
+Add the regular Spigot dependency to your `dependencies` scope:
+
+```kotlin
+dependencies {
+    compileOnly("org.spigotmc:spigot:1.16.5-R0.1-SNAPSHOT")
+}
+```
+
+Make sure that the version number before `-R0.1-SNAPSHOT` matches the version you have just built using the BuildTools.
+
+## Add KSpigot
+
+### Add the dependency
+
+Add the following repository to your `repositories` scope:
+
+```kotlin
+repositories {
+    mavenCentral()
+    maven("https://repo.codemc.io/repository/maven-snapshots/")
+}
+```
+
+Add the KSpigot dependency to your `dependencies` scope:
+
+```kotlin
+dependencies {
+    implementation("net.axay", "kspigot", "VERSION")
+}
+```
+
+Replace `VERSION` with the version you want to use. 
+
+Latest version (without the `v`): <br>
+![latest KSpigot GitHub release](https://img.shields.io/github/v/release/bluefireoly/KSpigot?label=latest%20version)
+
+### Shade KSpigot into your jar file
+
+Add the widely used shadow plugin:
+
+```kotlin
+plugins {
+    id("com.github.johnrengelman.shadow") version "VERSION"
+}
+```
+
+Replace `VERSION` with the version number from the following badge: <br>
+![latest shadow plugin version](https://api.bintray.com/packages/johnrengelman/gradle-plugins/gradle-shadow-plugin/images/download.png)
+
+#### Relocate KSpigot during the shadow process
+
+In order to avoid conflicts with other plugins, you should relocate KSpigot. This can be done using the shadow plugin from the previous step.
+
+Configure it like this:
+
+```kotlin
+tasks {
+    shadowJar {
+        relocate("net.axay.kspigot", "YOURMAINGROUP.shadow.net.axay.kspigot")
+    }
+}
+```
+
+Replace `YOURMAINGROUP` with the main package structure you use (e.g. `org.example.`)
+
+## Build your final plugin
+
+Run the Gradle task called `shadowJar`. Using IntelliJ IDEA, this can be done using the Gradle sidebar, where your can find the task under `Tasks > Shadow > shadowJar`. Alternatively, you can also run `./gradlew shadowJar` in your terminal.

guide/docs/setup/project.md

@@ -0,0 +1,33 @@
+In this guide we will assume that you are using or want to use Gradle.
+
+## Install Java
+
+You will need to have the JDK (Java Development Kit) installed.
+
+If you do not already have a JDK installed, you have several options:
+
+- [Windows](https://adoptopenjdk.net/)
+- Arch `pacman -S jdk-openjdk` (refer to the [archwiki](https://wiki.archlinux.org/index.php/Java#OpenJDK) for other versions)
+- Debian `apt install default-jdk` (refer to the [Debian Wiki](https://wiki.debian.org/Java/) for other versions)
+
+Please make sure that you know which version of Java you have just installed. If you just have one installation of Java, run `java -version` to get the current Java version on your system.
+
+## Create a project
+
+In IntelliJ IDEA, click on `File > New > Project` and choose `Gradle` on the sidebar in the popup window.
+
+Now choose the JDK which you have just installed.
+
+If you want to write your gradle build script in Kotlin, make sure to tick the `Kotlin DSL build script` checkbox. _(recommended)_
+
+Now select `Java` and `Kotlin/JVM` as your frameworks.
+
+After that, you can create your project.
+
+You may now continue with the [Setup using Gradle](gradle.md) guide.
+
+## Add the Spigot `plugin.yml`
+
+Create a new file called `plugin.yml` in the `resources` directory of your project.
+
+[Read the official documentation](https://www.spigotmc.org/wiki/plugin-yml/) for the Spigot plugin.yml file.

guide/mkdocs.yml

@@ -0,0 +1,33 @@
+site_name: KSpigot
+site_description: Extended Spigot and Bukkit API for Kotlin
+site_author: Jakob Kretzschmar
+copyright: Copyright © (2021) - Jakob Kretzschmar
+
+theme:
+  name: material
+  language: en
+  icon:
+    repo: fontawesome/brands/github
+  palette:
+    scheme: preference
+    primary: deep orange
+    accent: amber
+
+markdown_extensions:
+  - pymdownx.details
+  - pymdownx.highlight
+  - pymdownx.superfences
+  - toc:
+      permalink: true
+      toc_depth: 4
+
+repo_url: https://github.com/bluefireoly/KSpigot
+repo_name: bluefireoly/KSpigot
+
+nav:
+  - Home: index.md
+  - Setup:
+      - For absolute beginners: setup/beginners.md
+      - Starting a new project: setup/project.md
+      - Setup using Gradle: setup/gradle.md
+      - Entrypoint to your plugin: setup/entrypoint.md