JeremyStarTM/Engine
1
0
Fork 0
forked from StarOpenSource/Engine
Code Pull requests Activity Actions

Add documentation

Browse source
This commit is contained in:
JeremyStar™ 2024-06-16 15:52:33 +02:00
parent a26c8035c1
commit 9828409bb7
Signed by: JeremyStarTM
GPG key ID: E366BAEF67E4704D
17 changed files with 15107 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

15
docs/.gitignore vendored Normal file
View file

@ -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*

24
docs/Makefile Normal file
View file

@ -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"

20
docs/README.md Normal file
View file

@ -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
```

3
docs/babel.config.js Normal file
View file

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

8
docs/docs/getting-started/_category_.json Normal file
View file

@ -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."
}
}

7
docs/docs/getting-started/initializing.md Normal file
View file

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

108
docs/docs/getting-started/installing.mdx Normal file
View file

@ -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>
```

10
docs/docs/javadoc.md Normal file
View file

@ -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/)

43
docs/docs/welcome.md Normal file
View file

@ -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).

134
docs/docusaurus.config.ts Normal file
View file

@ -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;

14636
docs/package-lock.json generated Normal file
View file

File diff suppressed because it is too large Load diff

46
docs/package.json Normal file
View file

@ -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"
}
}

20
docs/sidebars.ts Normal file
View file

@ -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;

24
docs/src/css/custom.css Normal file
View file

@ -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);
}

0
docs/static/.nojekyll vendored Normal file
View file

1
docs/static/dist/engine.png vendored Symbolic link
View file

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

8
docs/tsconfig.json Normal file
View file

@ -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": "."
}
}