Start drafting API docs

Author: APickledWalrus

astro.config.mjs

@@ -4,9 +4,9 @@ import starlight from '@astrojs/starlight';
 
 // https://astro.build/config
 export default defineConfig({
-	integrations: [
-		starlight({
-			title: 'Skript',
+    integrations: [
+        starlight({
+            title: 'Skript',
             favicon: '/favicon.svg',
             /*logo: {
                 src: './src/assets/banner.webp',
@@ -29,9 +29,55 @@ export default defineConfig({
             editLink: {
                 baseUrl: 'https://github.com/SkriptLang/docs/edit/master/',
             },
-            pagination: false,
-		}),
-	],
+            sidebar: [
+                {
+                    label: 'Scripting',
+                    collapsed: true,
+                    autogenerate: {
+                        directory: 'scripting',
+                    },
+                },
+                {
+                    label: 'API',
+                    collapsed: true,
+                    items: [
+                        'api',
+                        {
+                            label: 'Skript',
+                            collapsed: true,
+                            autogenerate: {
+                                directory: 'api/skript',
+                            },
+                        },
+                        {
+                            label: 'Localization',
+                            collapsed: true,
+                            autogenerate: {
+                                directory: 'api/localization',
+                            },
+                        },
+                        {
+                            label: 'Syntax',
+                            collapsed: true,
+                            autogenerate: {
+                                directory: 'api/syntax',
+                            },
+                        },
+                        {
+                            label: 'Registries',
+                            collapsed: true,
+                            autogenerate: {
+                                directory: 'api/registries',
+                            },
+                        },
+                    ],
+                },
+            ],
+            expressiveCode: {
+                tabWidth: 4,
+            },
+        }),
+    ],
     redirects: {
         "tutorials": "/scripting",
         "events": "/syntaxes",

src/content/docs/api/index.mdx

@@ -1,8 +1,55 @@
 ---
 title: Getting Started
 tableOfContents: false
+sidebar:
+    order: 0
+prev: false
+next: false
 ---
 
+Welcome to the official documentation for Skript's API!
+
+Skript comprises dozens of interworking systems, each contributing to the process that makes it tick.
+It is important to understand that many parts of this API have been around since the beginning (more than 14 years ago), undergoing little to no change since then.
+While these systems continue to work, their age shows.
+They are intricately interwoven, and rewriting them to modern standards is no simple task, though we are making progress.
+As a result, some of these systems will seem relatively modern while others are in desperate need of attention.
+Regardless of status, the purpose of these pages is to provide a deeper explanation of how to best use these systems.
+
+## Expectations
+When working with Skript's API, it is strongly recommended that:
+- You have a strong understanding of Java
+- You have a strong understanding of using Skript
+    - That is, you can comfortably write scripts
+- You are not scared by old, cobweb-ridden code :)
+
+## Organization
+This documentation is organized by breaking up Skript into its major components (systems), and by breaking up each of these components into their subcomponents.
+For example, *syntax* is a major component of Skript, and there are many different kinds of syntax (expressions, statements, etc.).
+
+The cards below cover the major components covered by this documentation.
+
 import { CardGrid, LinkCard } from "@astrojs/starlight/components";
 
-We're happy to see you're interested in learning about the Skript API.
+<CardGrid>
+    <LinkCard
+        title="Skript"
+        description="The heart of Skript, where your journey begins."
+        href="skript"
+    />
+    <LinkCard
+        title="Localization"
+        description="Localization powers dynamic messages based on a user's preferences."
+        href="localization"
+    />
+    <LinkCard
+        title="Syntax"
+        description="Syntax is Skript's most core component, powering the scripts you write."
+        href="syntax"
+    />
+    <LinkCard
+        title="Registries"
+        description="Registries provide dynamic ways to interact with and expand Skript's functionality."
+        href="registries"
+    />
+</CardGrid>

src/content/docs/api/localization/index.mdx

@@ -0,0 +1,12 @@
+---
+title: Getting Started
+tableOfContents: false
+sidebar:
+    order: 0
+prev: false
+---
+
+Skript includes localization capabilities for changing its messages or translating them into other languages.
+First, this guide walks through the format of language files.
+Then, it describes the process for loading the translations defined by language files.
+Finally, it highlights what methods and utilities are available for working with these translations.

src/content/docs/api/localization/language-files.md

@@ -0,0 +1,27 @@
+---
+title: Language Files
+sidebar:
+    order: 10
+---
+
+By default, Skript has two core language files, `default.lang` and `english.lang`.
+The former is used for language entries that are *not* intended to be edited by the user,
+while the latter is for entries, such as error messages, that are safe to be translated into other languages.
+
+For addons, these language files are typically stored in a `lang` directory in your project's resources folder.
+Addons are not required to provide language files by default.
+Note that some features may require language entries, and if that is the case, the addon only has to provide a `default.lang` file.
+
+Within a language file, it is only required that you include a version entry:
+```
+// default.lang
+version: 1.0.0
+```
+
+Language entries are defined in a tree-like structure:
+```
+// default.lang
+error messages:
+    unknown error: An unknown error has occurred.
+```
+This entry would then be available under the key `error messages.unknown error`.

src/content/docs/api/localization/language.md

@@ -0,0 +1,10 @@
+---
+title: Language
+sidebar:
+    order: 30
+---
+
+:::danger[Under Construction]
+This page is still under construction!
+Check back for updates.
+:::

src/content/docs/api/localization/localizer.md

@@ -0,0 +1,58 @@
+---
+title: Localizer
+sidebar:
+    order: 20
+    badge:
+        text: Experimental
+        variant: caution
+---
+
+:::caution[Experimental]
+The API described in this page is still experimental and subject to change.
+However, there will be no breaking changes to methods detailed below.
+If necessary, they would only be deprecated for future removal.
+:::
+
+The Localizer is an **experimental** interface defining the methods available for localization.
+Currently, it is only used by addons to load their language files, which is described below.
+
+## Obtaining a Localizer
+A Localizer instance is available through your [registered addon](../../skript/addons) by calling the `localizer()` method:
+```java
+SkriptAddon addon = ...;
+Localizer addonLocalizer = addon.localizer();
+```
+
+## Loading language files
+The localizer currently provides a single method, `setSourceDirectories(String, String)` for loading an addon's language files.
+It takes two parameters:
+- A string representing the path to the directory (on the jar) containing language files
+- A string representing the path to the directory (on the disk) containing language files
+
+The second parameter may be null. That is, there is no requirement that you store language files outside your application's jar.
+However, you may wish to do so if you have language files that are intended to be customizable by the user.
+
+### Example usage
+Let's say my addon's language files are stored in a directory `lang` on the jar (as is typical).
+I can simply call the `setSourceDirectories` method with this path:
+```java
+Localizer localizer = ...;
+localizer.setSourceDirectories("lang", null);
+```
+After calling this method, Skript will immediately load the `default.lang` and `english.lang` (if present) files from that directory in your jar.
+
+## Evaluating entries
+The `translate(String)` method can be used for obtaining the translation of a language key (the parameter).
+This method will return `null` if there is no translation for the provided key.
+
+Let's say my addon's default language file has the following entry:
+```
+// default.lang
+error messages:
+    unknown error: An unknown error has occurred.
+```
+I can obtain its value by simply calling:
+```java
+Localizer localizer = ...;
+String message = localizer.translate("error messages.unknown error");
+```

src/content/docs/api/registries/arithmetic.md

@@ -0,0 +1,8 @@
+---
+title: Arithmetic
+---
+
+:::danger[Under Construction]
+This page is still under construction!
+Check back for updates.
+:::

src/content/docs/api/registries/comparators.md

@@ -0,0 +1,8 @@
+---
+title: Comparators
+---
+
+:::danger[Under Construction]
+This page is still under construction!
+Check back for updates.
+:::

src/content/docs/api/registries/converters.md

@@ -0,0 +1,8 @@
+---
+title: Converters
+---
+
+:::danger[Under Construction]
+This page is still under construction!
+Check back for updates.
+:::

src/content/docs/api/registries/experiments.md

@@ -0,0 +1,8 @@
+---
+title: Experiments
+---
+
+:::danger[Under Construction]
+This page is still under construction!
+Check back for updates.
+:::