docs: Add docs generator

0ffz · 0ffz · commit 435e5a51da84 · 2025-09-19T23:50:06.000-04:00
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,48 @@
+name: Publish Documentation
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - master
+    paths:
+      - 'docs/**'
+      - .github/workflows/docs.yml
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    name: Build docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: MineInAbyss/publish-action@v3
+        with:
+          publish-github-release: false
+          build-tasks: 'docsGenerate'
+
+      - name: Update HTML links for GitHub Pages subdomain
+        run: |
+          find out -name "*.html" -exec sed -i 's#href="/#href="/guiy-compose/#g; s#src="/#src="/guiy-compose/#g; s#"/assets#"/guiy-compose/assets#g' {} \;
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: out
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/.github/workflows/gradle-ci.yml b/.github/workflows/gradle-ci.yml
@@ -3,6 +3,7 @@ name: Java CI with Gradle
 on:
   pull_request:
     paths-ignore:
+      - docs
       - '**.md'
 
 concurrency:
diff --git a/.github/workflows/publish-packages.yml b/.github/workflows/publish-packages.yml
@@ -6,6 +6,7 @@ on:
       - master
       - develop
     paths-ignore:
+      - docs
       - '**.md'
 
 jobs:
diff --git a/README.md b/README.md
@@ -3,7 +3,7 @@
 # Guiy
 
 [![Maven](https://img.shields.io/maven-metadata/v?metadataUrl=https://repo.mineinabyss.com/releases/com/mineinabyss/guiy-compose/maven-metadata.xml)](https://repo.mineinabyss.com/#/releases/com/mineinabyss/guiy-compose)
-[![Contribute](https://shields.io/badge/Contribute-e57be5?logo=github%20sponsors&style=flat&logoColor=white)](https://wiki.mineinabyss.com/contribute/)
+[![Contribute](https://shields.io/badge/Contribute-e57be5?logo=github%20sponsors&style=flat&logoColor=white)](https://mineinabyss.com/contributing)
 </div>
 
 A Minecraft UI library for PaperMC, built on the Compose compiler.
@@ -35,7 +35,7 @@ guiy(player) {
 @Composable
 fun ExampleMenu() {
     // Guiy will dynamically update players, title, or height if you use a state.
-    Chest(title = "Example", height = 4, onClose = { exit() /*reopen()*/ }) {
+    Chest(title = "Example", modifier = Modifier.height(4), onClose = { exit() /*back()*/ }) {
         ToggleButton()
     }
 }
@@ -143,8 +143,9 @@ our [main project](https://github.com/MineInAbyss/MineInAbyss/tree/master/minein
 
 ```kotlin
 plugins {
-    // Match version in guiy's build.gradle.kts
-    id("org.jetbrains.compose") version "1.x.x"
+    // Try to match version in guiy's build.gradle.kts
+    id("org.jetbrains.kotlin.plugin.compose") version "<kotlin-version>"
+    id("org.jetbrains.compose") version "<compose-version>"
 }
 
 repositories {
diff --git a/build.gradle.kts b/build.gradle.kts
@@ -5,6 +5,7 @@ plugins {
     alias(idofrontLibs.plugins.mia.copyjar)
     alias(idofrontLibs.plugins.mia.publication)
     alias(idofrontLibs.plugins.mia.autoversion)
+    alias(idofrontLibs.plugins.mia.docs)
     alias(idofrontLibs.plugins.jetbrainsCompose)
     alias(idofrontLibs.plugins.compose.compiler)
 }
@@ -42,3 +43,7 @@ dependencies {
     implementation(idofrontLibs.bundles.idofront.core)
     implementation(idofrontLibs.idofront.nms)
 }
+
+idofront {
+    docsVersion = "0.0.4"
+}
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -0,0 +1,8 @@
+- [Home](/)
+- [Changelog](/changelog)
+- [Examples](/examples)
+
+# Usage
+
+- [Android Architecture](/usage/architecture)
+- [:barrier-block: Coming soon](/usage/inventories)
diff --git a/docs/TOPBAR.md b/docs/TOPBAR.md
@@ -0,0 +1 @@
+[:brand-github: GitHub](https://github.com/MineInAbyss/guiy-compose)
diff --git a/docs/changelog.md b/docs/changelog.md
@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+This project does NOT adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.14.0] - Unreleased
+
+### Added
+- New navigation system inspired by jetpack compose
+- Support for different inventory types like Anvil, and the ability to swap between them. See anvil gui example.
+- InventoryHolder system which manages switching between different inventories and manages viewers
+- Added some composables we created under MineInAbyss/MineInAbyss (ex. PlayerHead)
+- Back handler that pops navigation stack, or exits when empty by default
+- A basic `GuiyViewModel` class, and ability to register them with `viewModel { ... }`, and get them with `viewModel<MyViewModel>()`
+  - These also provide a `viewModelScope` for correctly collecting state in sync with UI updates.
+  - In the future, we plan to integrate with something like Koin for proper DI. Please note that currently ViewModels are tied to the composition as a whole, with an API for registering them per-screen coming later.
+  - NOTE: Android's ViewModels do a lot under the hood, our goal is not to match behaviour perfectly but to provide enough functionality to follow architecture best practices.
+- Some new composition locals, including `LocalGuiyOwner` and `CurrentPlayer` getter for getting the first viewer for a running guiy instance.
+
+### Changed
+- `onClose` doesn't require a `reopen` call anymore, instead reopening on its own. Call `exit` explicitly to exit (the default behaviour.)
+- Updates some composables to use nicer callbacks, ex. Paginated/Scrollable
+- Players are now passed once on gui creation, not per Inventory screen
+- Major internal cleanup and refactoring, unfortunately this leads to some package names changing
+
+### Fixed
+- Flickering GUIs when switching screens
+- Mouse cursor resetting when switching screens of the same height
+- Use an immediate-style Dispatcher to let compose correctly finish recompositions in one loop
+- Double clicks being sent as well as two single click events with the default `clickable` modifier. This lead to unexpected extra clicks by default which are now fixed.
diff --git a/docs/config.yml b/docs/config.yml
@@ -0,0 +1 @@
+name: Guiy
diff --git a/docs/examples.md b/docs/examples.md
@@ -0,0 +1,16 @@
+# Examples
+
+We provide usage examples under `guiy-examples` in the project repo.
+These show both how to include guiy in gradle and depend on it as a paper plugin, and contain different menus showcasing
+guiy's features.
+
+## Real-world examples
+
+These are notable projects using guiy-compose that you can use as a reference.
+Most are used internally at Mine in Abyss, however feel free to reach out to us on Discord if you'd like to add your own open source project here.
+
+| Reference                                                                                                                                                 | Description                                                                                                                                                                                                                        |
+|-----------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [Mine in Abyss plugin](https://github.com/MineInAbyss/MineInAbyss/tree/master/mineinabyss-features/src/main/kotlin/com/mineinabyss/features/guilds/menus) | Uses guiy for most of our menus, the largest of which is our guild system. We are working to rewrite this using android architecture standards, please only use this as a general reference for composables, not state management. |
+|                                                                                                                                                           |                                                                                                                                                                                                                                    |
+
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,186 @@
+<div align="center">
+
+# Guiy
+
+[![Maven](https://img.shields.io/maven-metadata/v?metadataUrl=https://repo.mineinabyss.com/releases/com/mineinabyss/guiy-compose/maven-metadata.xml)](https://repo.mineinabyss.com/#/releases/com/mineinabyss/guiy-compose)
+[![Contribute](https://shields.io/badge/Contribute-e57be5?logo=github%20sponsors&style=flat&logoColor=white)](https://mineinabyss.com/contributing)
+</div>
+
+A Minecraft UI library for PaperMC, built on the Compose compiler.
+
+While [Jetpack Compose](https://developer.android.com/jetpack/compose) is a commonly used UI toolkit in Android development,
+*the Compose compiler is just a tool to dynamically [manage trees](https://arunkumar.dev/jetpack-compose-for-non-ui-tree-construction-and-code-generation/)*.
+Guiy implements its own layouts, modifiers, and rendering specifically for Minecraft chest UI.
+This means you can work with state exactly as you would with Jetpack Compose, but without any overhead from Android, and with concepts native to Minecraft.
+
+> [!NOTE]
+> Guiy is in active development as we continue to try new use-cases in our plugins. We can't promise api stability yet,
+> but try to follow semver for breaking changes.
+
+## Examples
+
+See the `guiy-example` package for a full demonstration of project setup and different features.
+
+### Entry
+
+```kotlin
+guiy(player) {
+    ExampleMenu()
+}
+```
+
+### Chest menu
+
+```kotlin
+@Composable
+fun ExampleMenu() {
+    // Guiy will dynamically update players, title, or height if you use a state.
+    Chest(title = "Example", modifier = Modifier.height(4), onClose = { exit() /*back()*/ }) {
+        ToggleButton()
+    }
+}
+```
+
+### Toggle button
+
+```kotlin
+val RED = ItemStack(Material.RED_WOOL)
+val GREEN = ItemStack(Material.GREEN_WOOL)
+
+@Composable
+fun ToggleButton() {
+    var enabled by remember { mutableStateOf(false) }
+    val display = if (enabled) GREEN else RED
+    Item(display, Modifier.clickable {
+        enabled = !enabled
+    })
+}
+```
+
+### Modifiers
+
+We use a similar modifier system to Jetpack Compose.
+
+```kotlin
+// Entry to modifiers, though you are encouraged to pass a modifier parameter into your composables.
+Modifier
+    // Set the width of an element (can use min/max constraints, or .size to set width and height)
+    .width(3)
+    // Fill based on parent constraints like Jetpack
+    .fillmaxHeight()
+    // Padding in # of blocks
+    .padding(vertical = 1)
+    // Place at an offset
+    .offset(x = 1, y = 5)
+    // Do actions on click
+    .clickable { doSomething() }
+```
+
+### Alignment
+
+Guiy provides Row, Column, and Box components based on Jetpack's, these come with Arrangement and Alignment too. We also
+provide our components like Vertical/Horizontal Grids optimized for common Minecraft uses.
+
+```kotlin
+// A horizontal row of 10 items, with 1 space between each.
+Row(horizontalArrangement = Arrangement.spacedBy(1)) {
+    repeat(4) {
+        Item(...)
+    }
+}
+
+// Same but vertical
+Column { ... }
+
+// Two rows on top of each other
+Column {
+    Row { ... }
+    Row { ... }
+}
+
+// Items aligned left to right, top to bottom, wrapped to be smaller than width, useful for pages of items!
+VerticalGrid(Modifier.width(3)) {
+    repeat(7) {
+        Item(...)
+    }
+}
+/* Result:
+    III
+    III
+    I--   */
+```
+
+### Coroutines
+
+LaunchedEffect support, same as in Jetpack Compose:
+
+```kotlin
+fun TimedToggle() {
+    var enabled by remember { mutableStateOf(false) }
+    val display = if (enabled) GREEN else RED
+    Item(display)
+
+    LaunchedEffect(Unit) {
+        // Button will flash 10 times, with 1 second intervals
+        repeat(10) {
+            toggled = !toggled
+            delay(1000)
+        }
+    }
+}
+```
+
+### Real world use
+
+We are using this project internally, so you should be able to find up-to-date usage in
+our [main project](https://github.com/MineInAbyss/MineInAbyss/tree/master/mineinabyss-features/src/main/kotlin/com/mineinabyss/features/guilds/menus).
+
+## Usage
+
+### Gradle
+
+#### build.gradle.kts
+
+```kotlin
+plugins {
+    // Try to match version in guiy's build.gradle.kts
+    id("org.jetbrains.kotlin.plugin.compose") version "<kotlin-version>"
+    id("org.jetbrains.compose") version "<compose-version>"
+}
+
+repositories {
+    maven("https://maven.pkg.jetbrains.space/public/p/compose/dev")
+    maven("https://repo.mineinabyss.com/releases")
+}
+
+dependencies {
+    compileOnly("com.mineinabyss:guiy-compose:x.y.z")
+}
+```
+
+#### settings.gradle.kts
+
+```kotlin
+pluginManagement {
+    repositories {
+        google()
+        gradlePluginPortal()
+        maven("https://maven.pkg.jetbrains.space/public/p/compose/dev")
+    }
+}
+```
+
+### Server setup
+
+Guiy does not package the Kotlin runtime, it depends on our helper plugin Idofront using Paper's isolated dependency
+system.
+
+- [Download](https://github.com/MineInAbyss/guiy-compose/releases/latest) and install Guiy into your plugin folder.
+- [Download](https://github.com/MineInAbyss/Idofront/releases/latest) Idofront, a required dependency.
+- Depend on Guiy in a [paper-plugin](https://docs.papermc.io/paper/dev/getting-started/paper-plugins), this will give you access to Guiy and any libraries in Idofront in an isolated manner.
+
+## Thanks
+
+- Google for creating Jetpack Compose.
+- JetBrains for making it easy to use the compiler plugin outside of Android.
+- A lot of the inital code to set up the Jetpack Compose environment comes from https://github.com/JakeWharton/mosaic.
diff --git a/docs/usage/architecture.md b/docs/usage/architecture.md
@@ -0,0 +1,5 @@
+# Architecture
+
+Guiy encourages following Android's well-documented [app architecture standards](https://developer.android.com/topic/architecture). I highly recommend getting accustomed to the data and UI layers.
+
+Due to how compose is structured, we can't reuse many classes it provides directly. However, Guiy does its best to implement the minimum needed to follow the laid out recommendations (ex. we provide a simple ViewModel implementation, similar Modifier patterns, navigation, etc...)
diff --git a/docs/usage/inventories.md b/docs/usage/inventories.md
@@ -0,0 +1,3 @@
+# Coming soon
+
+We are working on creating documentation for guiy soon!
diff --git a/src/main/kotlin/com/mineinabyss/guiy/components/canvases/Anvil.kt b/src/main/kotlin/com/mineinabyss/guiy/components/canvases/Anvil.kt
@@ -1,13 +1,13 @@
 package com.mineinabyss.guiy.components.canvases
 
 import androidx.compose.runtime.*
+import com.mineinabyss.guiy.canvas.CurrentPlayer
+import com.mineinabyss.guiy.canvas.inventory.GuiyInventoryHolder
+import com.mineinabyss.guiy.canvas.inventory.InventoryCloseScope
 import com.mineinabyss.guiy.components.items.InvisibleItem
 import com.mineinabyss.guiy.components.rememberMiniMsg
 import com.mineinabyss.guiy.components.state.IntCoordinates
 import com.mineinabyss.guiy.guiyPlugin
-import com.mineinabyss.guiy.canvas.CurrentPlayer
-import com.mineinabyss.guiy.canvas.inventory.GuiyInventoryHolder
-import com.mineinabyss.guiy.canvas.inventory.InventoryCloseScope
 import com.mineinabyss.guiy.layout.Box
 import com.mineinabyss.guiy.layout.Row
 import com.mineinabyss.guiy.modifiers.Modifier
@@ -41,8 +41,7 @@ fun Anvil(
     var playerViewText by remember(inventory) { mutableStateOf("") }
     LaunchedEffect(player) {
         guiyPlugin.anvilPacketFlow.filter { it?.second == player }.filterNotNull().collect {
-            val text = if (it.first.isNotEmpty()) it.first
-            else inventory.getItem(0)?.effectiveName()?.toPlainText() ?: ""
+            val text = it.first.ifEmpty { inventory.getItem(0)?.effectiveName()?.toPlainText() ?: "" }
             playerViewText = text
             onTextChanged(text)
         }

-Original file line number
+Diff line change
       - master
       - develop
     paths-ignore:
 +      - docs
       - '**.md'
 jobs:
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+[:brand-github: GitHub](https://github.com/MineInAbyss/guiy-compose)`