start config docs + overhaul of contributing docs

LordIdra · LordIdra · commit 1317c040b655 · 2026-06-08T03:04:12.000+01:00
diff --git a/docs/en/documentation/contributing/custom-dokka.md b/docs/en/documentation/contributing/custom-dokka.md
@@ -0,0 +1,9 @@
+# Custom Dokka
+
+Pylon uses a custom version of Dokka to generate Javadocs. This is because the default Dokka output is very buggy and doesn't look very good. Seggan has submitted pull requests to the Dokka project to fix the issues, but they haven't been merged yet, so in the meantime we use a custom version. If you wish to see the "fixed" doc output, here are the steps:
+
+1. Clone the `pylonmc/dokka` repository: `git clone https://github.com/pylonmc/dokka`
+2. Checkout the `pylon` branch: `git checkout pylon`
+3. In the root directory, execute `./gradlew publishToMavenLocal -Pversion=2.1.0-pylon-SNAPSHOT`. Note that as Dokka is a very large project, the first build will take a long time. On Seggan's decent-ish laptop, the first run took about 10 minutes. Subsequent builds will be much faster as long s you don't delete the build cache.
+4. Now, in the Pylon master project, execute `./gradlew :rebar:rebar:dokkaGenerate -PusePylonDokka=true`. The generated output will be under `pylon/rebar/rebar/build/dokka`.
+
diff --git a/docs/en/documentation/contributing/getting-started.md b/docs/en/documentation/contributing/getting-started.md
@@ -1,43 +1,67 @@
-# Getting started
+!!! info "This guide covers contributing to both Pylon and Rebar, as the process is very similar."
 
-Rebar is written in [Kotlin](https://kotlinlang.org/), a language similar to Java, but with more modern features and concise syntax. If you know Java, you'll be able to pick up Kotlin very quickly.
+## What should I contribute?
 
-Pylon is written in Java.
+We generally welcome contributions for both Rebar and Pylon.
 
-## How to get started
+We use GitHub issues to keep track of tasks. Good first issues are labelled with the 'good first issue' tag. You can view good first issues for Rebar [here](https://github.com/pylonmc/rebar/issues?q=state%3Aopen%20label%3A%22good%20first%20issue%22) and for Pylon [here](https://github.com/pylonmc/pylon/issues?q=state%3Aopen%20label%3A%22good%20first%20issue%22). Picking one of these issues is a great place to start.
 
-1. Clone the `parallel-dev-repo` repository: `git clone https://github.com/pylonmc/parallel-dev-repo` (or use a GUI like Github Desktop)
-2. If you're using IntelliJ, it'll set everything up automatically. If not, run `./gradlew`. This will clone the `rebar` and `pylon` repositories.
-3. If you want to submit your changes to the master project, **delete the `rebar` or `pylon` directory (depending on which one you want to contribute to), fork the rebar or pylon repository, and clone your fork into the same directory.** Otherwise, you won't be able to open a pull request with your changes (unless you're a Rebar/Pylon developer and have access to the Rebar/Pylon repositories).
+If you'd like to do something which does not have an issue already (you can check this by searching for keywords in issues), we recommend you open an issue and assign yourself to it before completing the task. This helps avoid duplicate work and lets others know what you are doing.
+
+If you are planning on making a major change, we strongly recommend discussing with the team beforehand on the Pylon Discord server.
 
-See the [The Parallel Dev Repo Project](master-project.md) page for more information about the master repository.
+If you have any questions about contributing, feel free to ask us on the Pylon Discord.
 
-## Submitting your contributions
+## Prerequisites
 
-We generally welcome contributions for both Rebar and Pylon, but it's best check with the Pylon team before making any major changes, because we might already have something planned out that won't fit well with your changes. Hop on our Discord server and have a chat with us if you're interested in doing anything major, or have any questions about contributing :)
+### Contributing to Rebar
+- A GitHub account
+- A Git/GitHub client such as [GitHub Desktop](https://github.com/apps/desktop)
+- Knowledge of [Kotlin](https://kotlinlang.org/)
+- A Kotlin IDE (such as IntelliJ)
 
-Once you're done with your changes, open a pull request and give some information about what you did and why you did it.
+### Contributing to Pylon
+- A GitHub account
+- A Git/GitHub client such as [GitHub Desktop](https://github.com/apps/desktop)
+- Knowledge of Java
+- A Java IDE (such as IntelliJ)
 
-## Tests
+!!! question "What is Kotlin?"
+    Kotlin is a language similar to Java, but with more modern features and concise syntax. If you know Java, you'll be able to pick up Kotlin very quickly.
 
-Rebar has a set of integration tests. Tests should only be added for critical functionality such as block storage and recipes.
+## How to get started
+
+We use the **parallel dev repository** to develop Rebar and Pylon in parallel. We recommend you use this repository when contributing to Pylon, Rebar, or both.
 
-## Custom Dokka
+1. Clone the `parallel-dev-repo` repository: `git clone https://github.com/pylonmc/parallel-dev-repo` (or use a GUI like Github Desktop)
+2. If you're using IntelliJ, it should clone the `rebar` and `pylon` repositories into the project automatically. If not, run `./gradlew`.
 
-Pylon uses a custom version of Dokka to generate Javadocs. This is because the default Dokka output is very buggy and doesn't look very good. Seggan has submitted pull requests to the Dokka project to fix the issues, but they haven't been merged yet, so in the meantime we use a custom version. If you wish to see the "fixed" doc output, here are the steps:
+See the [parallel dev repo docs page](parallel-dev-repo.md) for more information about the parallel dev repository.
 
-1. Clone the `pylonmc/dokka` repository: `git clone https://github.com/pylonmc/dokka`
-2. Checkout the `pylon` branch: `git checkout pylon`
-3. In the root directory, execute `./gradlew publishToMavenLocal -Pversion=2.1.0-pylon-SNAPSHOT`. Note that as Dokka is a very large project, the first build will take a long time. On Seggan's decent-ish laptop, the first run took about 10 minutes. Subsequent builds will be much faster as long s you don't delete the build cache.
-4. Now, in the Pylon master project, execute `./gradlew :rebar:rebar:dokkaGenerate -PusePylonDokka=true`. The generated output will be under `pylon/rebar/rebar/build/dokka`.
+### Contributing to Rebar
+
+3. [Fork Rebar](https://github.com/pylonmc/rebar/fork) on GitHub
+4. Delete the `rebar` directory
+5. Clone your fork in place of the `rebar` directory you just deleted
+6. Make your changes
+7. [Test your changes](testing-your-changes.md)
+8. Commit and push your changes to your fork
+9. Open a pull request
+
+### Contributing to Pylon
+
+3. [Fork Pylon](https://github.com/pylonmc/pylon/fork) on GitHub
+4. Delete the `pylon` directory
+5. Clone your fork in place of the `pylon` directory you just deleted
+6. Make your changes
+7. [Test your changes](testing-your-changes.md)
+8. Commit and push your changes to your fork
+9. Open a pull request
 
 ## I'm stuck, what next?
 
-1. If it's Pylon specific, check if it's in the docs. If it's not Pylon specific, google it.
+1. If it's Pylon/Rebar specific, check if it's in the docs. If it's not Pylon/Rebar specific, google it.
 2. Search issues on the relevant repository to see if it's been mentioned
 3. Search relevant terms on our Discord server to see if it's been discussed before
 4. Ask a question on our Discord server
 
-
-[comment]: <> (TODO make this easier to comprehend, maybe add screenshots etc, less experienced users will have no idea what the fuck is going on from these instructions)
-
diff --git a/docs/en/documentation/contributing/master-project.md b/docs/en/documentation/contributing/master-project.md
diff --git a/docs/en/documentation/contributing/parallel-dev-repo.md b/docs/en/documentation/contributing/parallel-dev-repo.md
@@ -0,0 +1,34 @@
+# The Parallel Dev Repo Project
+
+PylonMC has a repository called `parallel-dev-repo`. This allows you to run Pylon using your very own home-baked version of Rebar, allowing you to test new features much more easily. We recommend you make changes to both Pylon and Rebar using the repository.
+
+## Project structure
+The project is structured as such:
+```
+pylon/
+  src/
+rebar/
+  dokka-plugin/
+  nms/
+  rebar/
+  test/
+```
+
+The `pylon` directory, unsurprisingly, contains the source code for Pylon.
+
+The `rebar` directory is more complicated. Inside it are four subprojects: `dokka-plugin`, `nms`, `rebar`, and `test`. 
+
+- `dokka-plugin` contains a custom Dokka plugin we use to help with formatting Rebar's Javadocs
+- `nms` contains all the Rebar code that touches server internals. It is in a separate subproject to effectively isolate potentially unstable code from the rest of the project
+- `rebar` contains the code for Rebar itself
+- `test` contains the automated tests for Rebar
+
+## Tasks
+The parallel dev repo contains a few tasks that are useful for development:
+
+| Task                         | Alias               | Description                                                                                                |
+|------------------------------|---------------------|------------------------------------------------------------------------------------------------------------|
+| `runServer`                  | `runSnapshotServer` | Runs a Minecraft server with the current version of Rebar and Pylon                                        |
+| `:pylon:runServer`      | `runStableServer`   | Runs a Minecraft server with the latest stable version of Rebar and the current version of Pylon                |
+| `:rebar:test:runServer` | `runLiveTests`      | Executes the automated tests for Rebar                                                                        |
+
diff --git a/docs/en/documentation/contributing/testing-your-changes.md b/docs/en/documentation/contributing/testing-your-changes.md
@@ -0,0 +1,22 @@
+## Testing your changes
+
+Please test your changes before opening a pull request.
+
+To test your changes, you should run a local server with your modified versions of Rebar and/or Pylon. If you are using the parallel dev repo, this is easy. In IntelliJ, open the gradle panel on the right, open 'parallel-dev-repo', open 'run paper', and double click 'runServer'. This will run a server with your local versions of Rebar and Pylon on it. Otherwise, you can run `./gradlew runServer` from the command line. You can join the server by starting Minecraft and connecting to `localhost`.
+
+## Debugging
+
+You can use a debugger on your code easily with IntelliJ. Ensure that the 'parallel-dev-repo \[runServer\]' run configuration is selected, and then click the debug button. This will launch a server and attach the debugger to it.
+
+By default, the debugger will also attach to gradle tasks, including compilation, which causes a significant slowdown. To fix this, edit the run configuration, click 'modify options', and uncheck 'debug gradle scripts'.
+
+!!! danger
+    If you are launching the tasks using the aliases from IntelliJ and attach the debugger, you will notice that it does not work. I have no idea why this happens. In order to successfully attach the debugger, you need to run the actual tasks, not the aliases. For example, instead of running `runSnapshotServer`, run `runServer`.
+
+## Automated tests
+
+Rebar has a set of automated tests. Due to the limited and annoying nature of automatically testing a Minecraft plugin, they should only be added for critical functionality such as block storage and recipes.
+
+!!! warning
+    Do not expect Rebar's automated tests to catch any issues in your code unless you are modifying specific parts of the core systems that they test, such as parts of the fluid ticking logic.
+
diff --git a/docs/en/documentation/overview.md b/docs/en/documentation/overview.md
@@ -1,5 +1,3 @@
-The Rebar docs are split into 4 parts:
-
 ### Javadocs / KDocs
 
 An automatically generated web view of the codebase which allows you to search names, view JavaDoc strings, and more. KDocs is the Kotlin version of Javadocs.
@@ -10,13 +8,13 @@ An automatically generated web view of the codebase which allows you to search n
 
 ### Reference
 
-Documentation which gives a more holistic overview of Rebar and certain Rebar systems, written for addon developers.
+Documentation which gives a complete overview of Rebar, written for addon developers.
 
 ---
 
 ### Internals
 
-Holistic documentation on how Rebar systems work intewrnally. You do not need to view this documentation unless you are working on Rebar itself.
+Holistic documentation on how Rebar systems work internally. You do not need to view this documentation unless you are working on Rebar itself.
 
 ---
 
diff --git a/docs/en/documentation/reference/blocks/creating-new-blocks.md b/docs/en/documentation/reference/blocks/creating-new-blocks.md
@@ -1,5 +1,3 @@
-# Custom blocks
-
 !!! warning "This section of the docs assumes you understand the basics of Rebar items."
 
 Adding a custom block requires 3 things:
diff --git a/docs/en/documentation/reference/blocks/interfaces.md b/docs/en/documentation/reference/blocks/interfaces.md
@@ -1,5 +1,3 @@
-# Block interfaces
-
 Rebar has a number of builtin interfaces which add custom behaviour to blocks. For example, there are interfaces which allow you to:
 
 - add fluid buffers ([RebarFluidBufferBlock](https://pylonmc.github.io/rebar/docs/javadoc/io/github/pylonmc/rebar/block/base/RebarFluidBufferBlock.html))
diff --git a/docs/en/documentation/reference/blocks/persistent-data.md b/docs/en/documentation/reference/blocks/persistent-data.md
@@ -1,5 +1,3 @@
-# Persistent data
-
 Since each physical block has a corresponding instance, you can store block data in your block's class.
 
 For example, consider a block which increments a counter by one every time it is right clicked:
diff --git a/docs/en/documentation/reference/blocks/settings.md b/docs/en/documentation/reference/blocks/settings.md
@@ -1,5 +1,3 @@
-# Settings
-
 Just like items, you can assign settings to a block.
 
 Suppose we have a block which counts up by one every time it is right clicked:
diff --git a/docs/en/documentation/reference/blocks/waila.md b/docs/en/documentation/reference/blocks/waila.md
@@ -1,5 +1,3 @@
-# WAILA
-
 WAILA (What Am I Looking At) shows information about the Rebar block you are looking at:
 
 ![WAILA example](img/waila-example.png)
diff --git a/docs/en/documentation/reference/configs/config-adapter.md b/docs/en/documentation/reference/configs/config-adapter.md
diff --git a/docs/en/documentation/reference/configs/config-and-config-section.md b/docs/en/documentation/reference/configs/config-and-config-section.md
@@ -1,6 +1,28 @@
-As you probably know, in Minecraft plugins, configs are stored in YAML. Normally in Bukkit/Paper, you would use [YamlConfiguration](https://jd.papermc.io/paper/26.1.2/org/bukkit/configuration/file/YamlConfiguration.html) and [ConfigurationSection](https://jd.papermc.io/paper/26.1.2/org/bukkit/configuration/ConfigurationSection.html) to read a config file. `YamlConfiguration` and `ConfigurationSection` have a lot of quirks, lack a lot of useful functionality, and are inflexible. Because of this (well, there are other reasons, described shortly) we did what every developer does when they encounter a problem: create a new level of abstraction. Sorry.
+As you probably know, in Minecraft plugins, configs are stored in YAML. Normally in Bukkit/Paper, you would use [YamlConfiguration](https://jd.papermc.io/paper/26.1.2/org/bukkit/configuration/file/YamlConfiguration.html) and [ConfigurationSection](https://jd.papermc.io/paper/26.1.2/org/bukkit/configuration/ConfigurationSection.html) to read a config file. `YamlConfiguration` and `ConfigurationSection` have a lot of quirks, lack a lot of useful functionality, and are inflexible. Because of this, we did what every developer does when they encounter a problem: create a new level of abstraction. Sorry.
+
+The config-related things added by Rebar are:
+- [Config](https://pylonmc.github.io/rebar/docs/javadoc/io/github/pylonmc/rebar/config/Config.html)
+- [ConfigSection](https://pylonmc.github.io/rebar/docs/javadoc/io/github/pylonmc/rebar/config/ConfigSection.html)
+- []
+
+## Copying config 
+
 
 Enter [Config](https://pylonmc.github.io/rebar/docs/javadoc/io/github/pylonmc/rebar/config/Config.html) and [ConfigSection](https://pylonmc.github.io/rebar/docs/javadoc/io/github/pylonmc/rebar/config/ConfigSection.html). `Config` is a simple wrapper around `YamlConfiguration` and `ConfigSection` is a simple wrapper around `ConfigurationSection`.
 
+To read from a `ConfigSection`, you can use a `ConfigAdapter`. A `ConfigAdapter` is just a class which explains how to turn a part of config into a Java/Kotlin value. For example, the `ConfigAdapter.INT` config adapter allows an integer to be read from a config.
+
+## Examples
+
+To make this clearer, here are some examples.
+
+### Example 1
 
+```yaml title="pylon/some_config.yml"
+some-value: 5
+some-other-value: "hello"
+```
 
+```java
+int x = 
+```
diff --git a/docs/en/documentation/reference/multiblocks/multiblock-state.md b/docs/en/documentation/reference/multiblocks/multiblock-state.md
@@ -1,5 +1,3 @@
-# Multiblock state
-
 You will often need to get or listen for information about a multiblock's state. There are two main pieces of information tracked by Rebar that are important to know about:
 
 * Is the multiblock formed?
diff --git a/docs/en/documentation/reference/multiblocks/simple-multiblocks.md b/docs/en/documentation/reference/multiblocks/simple-multiblocks.md
@@ -1,5 +1,3 @@
-# Simple multiblocks
-
 In Rebar, there are two classes that handle multiblock: [RebarMultiblock](https://pylonmc.github.io/rebar/docs/javadoc/io/github/pylonmc/rebar/block/base/RebarMultiblock.html) and [RebarSimpleMultiblock](https://pylonmc.github.io/rebar/docs/javadoc/io/github/pylonmc/rebar/block/base/RebarSimpleMultiblock.html). 
 
 This page only covers `RebarSimpleMultiblock` as it is the simpler of the two and provides nice abstractions for working with multiblocks, while `RebarMultiblock` is far more flexible but also barebones.
diff --git a/docs/en/progress.md b/docs/en/progress.md
diff --git a/mkdocs.yml b/mkdocs.yml

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,3 @@`
`1`		`-# Custom blocks`
`2`		`-`
`3`	`1`	`!!! warning "This section of the docs assumes you understand the basics of Rebar items."`
`4`	`2`
`5`	`3`	`Adding a custom block requires 3 things:`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,3 @@`
`1`		`-# Block interfaces`
`2`		`-`
`3`	`1`	`Rebar has a number of builtin interfaces which add custom behaviour to blocks. For example, there are interfaces which allow you to:`
`4`	`2`
`5`	`3`	`- add fluid buffers ([RebarFluidBufferBlock](https://pylonmc.github.io/rebar/docs/javadoc/io/github/pylonmc/rebar/block/base/RebarFluidBufferBlock.html))`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,3 @@`
`1`		`-# Persistent data`
`2`		`-`
`3`	`1`	`Since each physical block has a corresponding instance, you can store block data in your block's class.`
`4`	`2`
`5`	`3`	`For example, consider a block which increments a counter by one every time it is right clicked:`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,3 @@`
`1`		`-# Settings`
`2`		`-`
`3`	`1`	`Just like items, you can assign settings to a block.`
`4`	`2`
`5`	`3`	`Suppose we have a block which counts up by one every time it is right clicked:`