Add documentation

docs/.gitignore

@@ -0,0 +1,15 @@
+/node_modules
+/out
+.docusaurus
+.cache-loader
+
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+pnpm-lock.yaml
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs/Makefile

@@ -0,0 +1,24 @@
+.PHONY: dist help
+
+dist: help
+help:
+	@echo "make install-deps  -> Install all dependencies"
+	@echo "     test          -> Start a web server for development"
+	@echo "     build         -> Build static files"
+	@echo "     clean         -> Clean directory"
+	@echo "     clean-extra   -> Clean directory with extra directories/files"
+install-deps:
+	pnpm install
+test:
+	pnpm run start --hot-only --no-open
+build:
+	pnpm run build --out-dir out
+clean:
+	pnpm run clear
+	rm -rf "out" ".docusaurus" ".cache-loader"
+clean-extra: clean
+	rm -rf "node_modules" "pnpm-lock.yaml"
+
+# The nuclear option, dunno why I made this
+clean-ultra: clean-extra
+	rm -rf "~/.cache/pnpm" "~/.local/share/pnpm" "~/.local/state/pnpm"

docs/README.md

@@ -0,0 +1,20 @@
+# sos!engine documentation
+The StarOpenSource Project uses [Docusaurus](https://docusaurus.io) for generating sos!engine's documentation.
+
+# Commands
+```bash
+# Installs all required dependencies
+make install-deps
+
+# Starts a development server with support for hot reloading
+make test
+
+# Build the documentation to 'out/'
+make build
+
+# Remove 'out/' directory as well as some of Docusaurus' files
+make clean
+
+# If you want to remove node_modules and other pnpm stuff execute this
+make clean-extra
+```

docs/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

docs/docs/getting-started/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Getting started",
+  "position": 2,
+  "link": {
+    "type": "generated-index",
+    "description": "Contains pages explaining how to setup the sos!engine in your project."
+  }
+}

docs/docs/getting-started/initializing.md

@@ -0,0 +1,7 @@
+---
+sidebar_position: 1
+title: Initializing
+---
+
+# Initializing
+## TODO

docs/docs/getting-started/installing.mdx

@@ -0,0 +1,108 @@
+---
+sidebar_position: 0
+title: Installing the engine
+---
+
+# Installing the engine
+
+```mdx-code-block
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+```
+
+## Gradle
+Add StarOpenSource's maven repository to your `build.gradle` file first:
+<Tabs groupId="maven-repository">
+<TabItem value="gradle-groovy-dsl" label="Groovy DSL">
+```groovy
+repositories {
+    mavenCentral()
+    
+    // sos!engine's maven repository
+    maven {
+        name "staropensource-sosengine"
+        url "https://mvn.staropensource.de/sosengine"
+    }
+}
+```
+</TabItem>
+<TabItem value="gradle-kotlin-dsl" label="Kotlin DSL">
+```kotlin
+repositories {
+    mavenCentral()
+
+    // sos!engine's maven repository
+    maven {
+        name = "staropensource-sosengine"
+        url = uri("https://mvn.staropensource.de/sosengine")
+    }
+}
+```
+</TabItem>
+</Tabs>
+
+After that declare the engine as a dependency to your project in the `build.gradle` file:
+<Tabs groupId="maven-dependencies">
+<TabItem value="gradle-groovy-dsl" label="Groovy DSL">
+```groovy
+dependencies {
+    // sos!engine base
+    implementation 'de.staropensource.sosengine:base:' + project.dependencyStarOpenSourceEngine
+    
+    // sos!engine subsystems
+    //implementation 'de.staropensource.sosengine:slf4j-compat:' + project.dependencyStarOpenSourceEngine // for SLF4J compatibility
+}
+```
+</TabItem>
+<TabItem value="gradle-kotlin-dsl" label="Kotlin DSL">
+```kotlin
+dependencies {
+    // sos!engine base
+    implementation("de.staropensource.sosengine:base:" + project.dependencyStarOpenSourceEngine)
+
+    // sos!engine subsystems
+    //implementation("de.staropensource.sosengine:slf4j-compat:" + project.dependencyStarOpenSourceEngine) // for SLF4J compatibility
+}
+```
+</TabItem>
+</Tabs>
+
+... and add this property to the `settings.gradle` file:
+```properties
+# Set this to the engine version you want to use
+dependencyStarOpenSourceEngine=1-alpha0
+```
+
+## Maven
+Add StarOpenSource's maven repository to your `pom.xml` file first:
+```xml
+<repositories>
+    <!-- sos!engine's maven repository -->
+    <repository>
+        <id>staropensource-sosengine</id>
+        <name>StarOpenSource's sos!engine maven repository</name>
+        <url>https://mvn.staropensource.de/sosengine</url>
+    </repository>
+</repositories>
+```
+
+After that declare the engine as a dependency to your project:
+```xml
+<dependencies>
+    <!-- sos!engine base -->
+    <dependency>
+        <groupId>de.staropensource.sosengine</groupId>
+        <artifactId>base</artifactId>
+        <version>1-alpha0</version>
+    </dependency>
+    
+    <!-- sos!engine subsystems -->
+    <!-- For SLF4J Compatibility
+      <dependency>
+          <groupId>de.staropensource.sosengine</groupId>
+          <artifactId>slf4j-compat</artifactId>
+          <version>1-alpha0</version>
+      </dependency>
+    -->
+</dependencies>
+```

docs/docs/javadoc.md

@@ -0,0 +1,10 @@
+---
+sidebar_position: 1
+title: JavaDoc
+---
+
+# API Documentation
+The engine API documentation covers the core engine and all official subsystems.
+
+- [Latest commit (updates every hour)](https://jd.engine.staropensource.de/develop/)
+- [v1-alpha0](https://jd.engine.staropensource.de/v1-alpha0/)

docs/docs/welcome.md

@@ -0,0 +1,43 @@
+---
+sidebar_position: 0
+title: Welcome
+---
+
+# sos!engine documentation
+Welcome to the documentation for the StarOpenSource Engine!
+<!-- StarOpenSource Fly verification links -->
+<link href="https://fly.staropensource.de/@staropensource" rel="me"/>
+<link href="https://fly.staropensource.de/@soscore" rel="me"/>
+<link href="https://fly.staropensource.de/@sosengine" rel="me"/>
+<!-- StarOpenSource Fly verification links -->
+
+## What is it?
+The StarOpenSource Engine (or **sos!engine** for short) is a modular, extensible and easy to use Java game and application engine. \
+It is responsible for the logging infrastructure, displaying stuff to a monitor, talking with graphics cards, playing audio, displaying UIs and much more.
+
+## Why another one?
+Yeah, it's true that there are many game engines and frameworks out there that intend to ease development of applications and games.
+I ([JeremyStarTM](https://git.staropensource.de/JeremyStarTM)) however have never seen an engine or framework that can be extended easily.
+And I don't mean what you make within the bounds of the engine or framework, no, I mean the engine/framework itself.
+
+## Architecture of the engine
+The engine consists of the core engine (`base` dependency in your project) and various subsystems (`slf4j-compat`, `graphics`, etc.). \
+ \
+The job of the base engine is to provide minimal classes and interfaces needed for an application.
+It contains among other things a default logger implementation, useful methods, event system and a placeholder system. \
+ \
+Subsystems on the other hand usually handle complex tasks. They provide abstractions for libraries and operating system calls. \
+"But why are there so many of them?" you might ask. Good question! Subsystems are intended to [do one thing and do it well](https://en.wikipedia.org/wiki/Unix_philosophy).
+
+## Available official subsystems
+Besides the `base` engine, there is one stable subsystem, two experimental subsystems and one stub subsystem.
+### Stable
+- [`slf4j-compat`](https://git.staropensource.de/StarOpenSource/Engine/src/branch/develop/slf4j-compat): Provides [SLF4J](https://slf4j.org/) compatibility logger that redirects all log calls to the engine.
+### Experimental
+- [`graphics`](https://git.staropensource.de/StarOpenSource/Engine/src/branch/develop/graphics): Provides interfaces and classes meant to be extended by Graphics APIs.
+- [`graphics-opengl`](https://git.staropensource.de/StarOpenSource/Engine/src/branch/develop/graphics/opengl): Provides the OpenGL Graphics API
+### Stub
+- [`graphics-vulkan`](https://git.staropensource.de/StarOpenSource/Engine/src/branch/develop/graphics/vulkan): Provides the Vulkan Graphics API. 100% unfinished, planned in the future.
+
+## API documentation
+To read the engine API documentation, visit [jd.engine.staropensource.de](https://jd.engine.staropensource.de).

docs/docusaurus.config.ts

@@ -0,0 +1,134 @@
+import {themes as prismThemes} from "prism-react-renderer";
+import type {Config} from "@docusaurus/types";
+import type * as Preset from "@docusaurus/preset-classic";
+
+const config: Config = {
+    title: "StarOpenSource Engine",
+    url: "https://engine.staropensource.de",
+    baseUrl: "/",
+    
+    favicon: "dist/core.png",
+    trailingSlash: true,
+    i18n: {
+        defaultLocale: "en",
+        locales: [ "en" ],
+    },
+    noIndex: false,
+    onBrokenLinks: "throw",
+    onBrokenAnchors: "throw",
+    onBrokenMarkdownLinks: "throw",
+    onDuplicateRoutes: "warn",
+    /*
+    onBrokenLinks: "ignore",
+    onBrokenAnchors: "ignore",
+    onBrokenMarkdownLinks: "ignore",
+    onDuplicateRoutes: "ignore",
+    */
+    tagline: "A modular, extensible and easy to use Java game and application engine.",
+    
+    themeConfig: {
+        docs: {
+            sidebar: {
+                hideable: true,
+                autoCollapseCategories: true,
+            },
+        },
+        navbar: {
+            title: "sos!engine",
+            logo: {
+                alt: "Engine Logo",
+                src: "dist/engine.png",
+                href: '/welcome',
+            },
+            items: [
+                {
+                    type: "docSidebar",
+                    sidebarId: "sidebar",
+                    label: "Documentation",
+                    position: "left",
+                },
+                {
+                    href: "https://jd.engine.staropensource.de",
+                    label: "JavaDoc",
+                    position: "left",
+                },
+                {
+                    href: "https://develop.core.staropensource.de",
+                    label: "Development documentation",
+                    position: "right",
+                },
+                {
+                    href: "https://git.staropensource.de/StarOpenSource/Engine",
+                    label: "Source code",
+                    position: "right",
+                },
+            ],
+        },
+        footer: {
+            style: "dark",
+            copyright: `Copyright (c) ${new Date().getFullYear()} The StarOpenSource Project & Contributors<br/>Licensed under the GNU Affero General Public License version 3<br/>Documentation generated with <a href="docusaurus.io">Docusaurus</a>`,
+        },
+        prism: {
+            theme: prismThemes.github,
+            darkTheme: prismThemes.dracula,
+        },
+    } satisfies Preset.ThemeConfig,
+    
+    presets: [
+        [
+            "classic", {
+                debug: false,
+
+                docs: {
+                    path: "docs",
+                    editUrl: "https://git.staropensource.de/StarOpenSource/Engine/_edit/develop/docs/",
+                    editLocalizedFiles: false,
+                    editCurrentVersion: true,
+                    routeBasePath: "",
+                    tagsBasePath: 'tags',
+                    sidebarPath: "./sidebars.ts",
+                    sidebarCollapsible: false,
+                    sidebarCollapsed: false,
+                    showLastUpdateAuthor: true,
+                    showLastUpdateTime: true,
+                    breadcrumbs: true,
+                    includeCurrentVersion: true,
+                },
+                sitemap: {
+                    changefreq: "monthly",
+                    priority: 0.5,
+                    filename: "sitemap.xml",
+                },
+                theme: {
+                    customCss: "./src/css/custom.css",
+                },
+            } satisfies Preset.Options,
+        ],
+    ],
+    
+    plugins: [
+        [
+            "@docusaurus/plugin-client-redirects",
+            {
+                fromExtensions: ["html", "htm", "php"],
+                redirects: [
+                    {
+                        from: ["/", "/index"],
+                        to: "/welcome",
+                    },
+                ],
+            },
+        ],
+    ],
+    
+    markdown: {
+        format: "detect",
+        mermaid: false,
+    },
+    
+    staticDirectories: ["static"],
+    titleDelimiter: "»",
+    baseUrlIssueBanner: true,
+};
+
+export default config;

docs/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "docs",
+  "version": "0.0.0",
+  "private": true,
+  "scripts": {
+    "docusaurus": "docusaurus",
+    "start": "docusaurus start",
+    "build": "docusaurus build",
+    "swizzle": "docusaurus swizzle",
+    "deploy": "docusaurus deploy",
+    "clear": "docusaurus clear",
+    "serve": "docusaurus serve",
+    "write-translations": "docusaurus write-translations",
+    "write-heading-ids": "docusaurus write-heading-ids",
+    "typecheck": "tsc"
+  },
+  "dependencies": {
+    "@docusaurus/core": "3.4.0",
+    "@docusaurus/plugin-client-redirects": "^3.4.0",
+    "@docusaurus/plugin-content-docs": "^3.4.0",
+    "@docusaurus/plugin-sitemap": "^3.4.0",
+    "@docusaurus/preset-classic": "3.4.0",
+    "@mdx-js/react": "^3.0.1",
+    "clsx": "^2.1.0",
+    "prism-react-renderer": "^2.3.1",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@docusaurus/module-type-aliases": "3.4.0",
+    "@docusaurus/tsconfig": "3.4.0",
+    "@docusaurus/types": "3.4.0",
+    "@types/node": "^20.12.5",
+    "typescript": "~5.4.4"
+  },
+  "browserslist": [
+      ">0.5%",
+      "not dead",
+      "not op_mini all",
+      "last 3 version",
+      "Firefox ESR"
+  ],
+  "engines": {
+    "node": ">=18.0"
+  }
+}

docs/sidebars.ts

@@ -0,0 +1,20 @@
+import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
+
+const sidebars: SidebarsConfig = {
+  sidebar: [{type: 'autogenerated', dirName: '.'}],
+
+  // But you can create a sidebar manually
+  /*
+  tutorialSidebar: [
+    'intro',
+    'hello',
+    {
+      type: 'category',
+      label: 'Tutorial',
+      items: ['tutorial-basics/create-a-document'],
+    },
+  ],
+   */
+};
+
+export default sidebars;

docs/src/css/custom.css

@@ -0,0 +1,24 @@
+:root {
+  --ifm-color-primary: #d60532;
+  --ifm-color-primary-dark: #c4052e;
+  --ifm-color-primary-darker: #af072b;
+  --ifm-color-primary-darkest: #990525;
+  --ifm-color-primary-light: #db1943;
+  --ifm-color-primary-lighter: #ec2c56;
+  --ifm-color-primary-lightest: #fa3e67;
+  --ifm-code-font-size: 95%;
+  --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1);
+}
+
+/* For readability concerns, you should choose a lighter palette in dark mode.
+   JeremyStarTM: Readability concerns? Fuck that shit. */
+[data-theme='dark'] {
+  --ifm-color-primary: #d60532;
+  --ifm-color-primary-dark: #c4052e;
+  --ifm-color-primary-darker: #af072b;
+  --ifm-color-primary-darkest: #990525;
+  --ifm-color-primary-light: #db1943;
+  --ifm-color-primary-lighter: #ec2c56;
+  --ifm-color-primary-lightest: #fa3e67;
+  --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
+}

docs/static/dist/engine.png

@@ -0,0 +1 @@
+../../../dist/branding/current.png

docs/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  // This file is not used in compilation. It is here just for a nice editor experience.
+  "extends": "@docusaurus/tsconfig",
+  "compilerOptions": {
+    "jsx": "react",
+    "baseUrl": "."
+  }
+}