Substantial documentation refactor

pewpewlive · Mar 24, 2024 · 9bd3cb6 · 9bd3cb6
1 parent bf1ba2c
commit 9bd3cb6
Show file tree

Hide file tree

Showing 23 changed files with 1,014 additions and 335 deletions.
diff --git a/blog/2024-03-20-first-blog-post.md b/blog/2024-03-20-first-blog-post.md
@@ -5,7 +5,7 @@ authors: tastykiwi
 tags: [first]
 ---
 
-Welcome to the first blog article! We are so excited to move the entirety of PPL level development documentation here. This platform allows us to make more interactive (via React components), good looking documentation and having powerful search powered by Algolia!
+Welcome to the first blog article! We are so excited to move the entirety of PPL level development documentation here. This platform allows us to make more interactive (via React components), good looking documentation and having powerful search!
 
 I hope you'll like the new home for PewPew docs.
 

diff --git a/docs/file-information/manifest-files.md → docs/File Information/manifest-files.md b/docs/file-information/manifest-files.md → docs/File Information/manifest-files.md
diff --git a/docs/file-information/mesh-files.md → docs/File Information/mesh-files.md b/docs/file-information/mesh-files.md → docs/File Information/mesh-files.md
@@ -47,6 +47,6 @@ The _optional_ `colors` field contains the colors of each vertexes. If the `colo
 
 Note that all meshes are rendered with additive blending.
 
-# Procedural rendering
+## Procedural rendering
 
 Astute readers may have realized that because `meshes` is described in a Lua script, it can be generated at runtime. See for instance this [example](https://github.com/jyaif/ppl-utils/blob/d32dbec8a171c9bcc0f800dcd864f175c42c34fd/content/levels/advanced_graphics/polar_graphic.lua#L36).
diff --git a/docs/file-information/sound-files.md → docs/File Information/sound-files.md b/docs/file-information/sound-files.md → docs/File Information/sound-files.md
diff --git a/docs/lua-guides/advanced.md → docs/Guides/Lua/advanced.md b/docs/lua-guides/advanced.md → docs/Guides/Lua/advanced.md
diff --git a/docs/lua-guides/beginner.md → docs/Guides/Lua/beginner.md b/docs/lua-guides/beginner.md → docs/Guides/Lua/beginner.md
diff --git a/docs/lua-guides/intermediate.md → docs/Guides/Lua/intermediate.md b/docs/lua-guides/intermediate.md → docs/Guides/Lua/intermediate.md
diff --git a/docs/other-guides/60-fps-animation.mdx → docs/Guides/Other/60-fps-animation.mdx b/docs/other-guides/60-fps-animation.mdx → docs/Guides/Other/60-fps-animation.mdx
diff --git a/docs/api/Fmath.md b/docs/api/Fmath.md
@@ -0,0 +1,112 @@
+---
+sidebar_position: 3
+---
+
+<!-- markdownlint-disable -->
+
+# fmath library
+
+`fmath` contains a set of mathematical functions that work with FixedPoint numbers and integers. `fmath` replaces Lua's `math` library in game scripts (you can use Lua's `math` library outside of game scripts).
+
+[//]: # "This file is automatically generated."
+[//]: # "Manual edits will be overwritten."
+
+## Functions
+### `max_fixedpoint()`
+```tsx
+fmath.max_fixedpoint(): FixedPoint
+```
+Returns the maximum value a fixedpoint integer can take.
+
+
+---
+### `random_fixedpoint()`
+```tsx
+fmath.random_fixedpoint(
+  min: FixedPoint,
+  max: FixedPoint
+): FixedPoint
+```
+Returns a random fixedpoint value in the range [`min`, `max`]. `max` must be greater or equal to `min`.
+
+
+---
+### `random_int()`
+```tsx
+fmath.random_int(
+  min: int,
+  max: int
+): int
+```
+Returns an integer in the range [`min`, `max`]. `max` must be greater or equal to `min`.
+
+
+---
+### `sqrt()`
+```tsx
+fmath.sqrt(x: FixedPoint): FixedPoint
+```
+Returns the square root of `x`. `x` must be greater or equal to 0.
+
+
+---
+### `from_fraction()`
+```tsx
+fmath.from_fraction(
+  numerator: int,
+  denominator: int
+): FixedPoint
+```
+Returns the fixedpoint value representing the fraction `numerator`/`denominator`. `denominator` must not be equal to zero.
+
+
+---
+### `to_int()`
+```tsx
+fmath.to_int(value: FixedPoint): int
+```
+Returns the integral part of the `value`.
+
+
+---
+### `abs_fixedpoint()`
+```tsx
+fmath.abs_fixedpoint(value: FixedPoint): FixedPoint
+```
+Returns the absolute value.
+
+
+---
+### `to_fixedpoint()`
+```tsx
+fmath.to_fixedpoint(value: int): FixedPoint
+```
+Returns a fixedpoint value with the integral part of `value`, and no fractional part.
+
+
+---
+### `sincos()`
+```tsx
+fmath.sincos(angle: FixedPoint): FixedPoint, FixedPoint
+```
+Returns the sinus and cosinus of `angle`. `angle` is in radian.
+
+
+---
+### `atan2()`
+```tsx
+fmath.atan2(
+  y: FixedPoint,
+  x: FixedPoint
+): FixedPoint
+```
+Returns the principal value of the arc tangent of y/x. Returns a value in the range [0, 2π[.
+
+
+---
+### `tau()`
+```tsx
+fmath.tau(): FixedPoint
+```
+Returns τ (aka 2π).
+
diff --git a/docs/api/pewpew-library.md → docs/api/PewPew.md b/docs/api/pewpew-library.md → docs/api/PewPew.md
diff --git a/docs/api/_category_.json b/docs/api/_category_.json
diff --git a/docs/api/fmath-library.md b/docs/api/fmath-library.md
diff --git a/docs/api/types.mdx b/docs/api/types.mdx
@@ -58,5 +58,4 @@ Typically used to hold text and file paths. The API only accepts strings less th
 
 ## float
 
-Stores floating point numbers. Because they make determinism hard to guarantee, floats must only be used in Lua scripts that define meshes or sounds. Although it is still technically possible to use floats in game scripts, they will eventually be forbidden.
-../../src/components/fx-converter
+Stores floating point numbers. Because they make determinism hard to guarantee, floats must only be used in Lua scripts that define meshes or sounds. Although it is still technically possible to use floats in game scripts, they will eventually be forbidden.
diff --git a/docs/file-information/_category_.json b/docs/file-information/_category_.json
diff --git a/docs/intro.md b/docs/intro.md
@@ -6,30 +6,30 @@ sidebar_position: 1
 
 This community-maintained wiki holds the resources useful for creating custom levels for PewPew Live.
 
-Levels are created by writing Lua code. If you are new to programming or new to Lua, a good first step is to start with the [Beginner](lua-guides/beginner) guide.
+Levels are created by writing Lua code. If you are new to programming or new to Lua, a good first step is to start with the [Beginner](Guides/Lua/beginner) guide.
 
 If you are already familiar with programming, a good approach is to first look at the examples (for example, the [simple_level]) to get a feeling of how a level is made, and then come back to the wiki to get more precise information about the various aspect of level creation.
 
 If you have questions, the game's creator and many level creators are available on [Discord].
 
-# Level structure
+## Level structure
 
-A level is a directory that contains a [manifest](file-information/manifest-files) and Lua files. The Lua files fall in three categories:
+A level is a directory that contains a [manifest](File%20Information/manifest-files) and Lua files. The Lua files fall in three categories:
 
-- Files that describe [graphics](file-information/mesh-files).
-- Files that describe [sounds](file-information/sound-files).
-- Files that describe the behavior of the level. They make use of the [pewpew](api/pewpew-library) and [fmath](api/fmath-library) libraries, which require an understanding of the [types](api/types) used.
+- Files that describe [graphics](File%20Information/mesh-files).
+- Files that describe [sounds](File%20Information/sound-files).
+- Files that describe the behavior of the level. They make use of the [pewpew](API/PewPew) and [fmath](API/Fmath) libraries, which require an understanding of the [types](API/types) used.
 
-# Uploading your level
+## Uploading your level
 
 You can upload your level by signing into your account on [https://pewpew.live] and navigating to the _Manage your custom levels_ page.
 
-# Recommended Lua Style guide
+## Recommended Lua Style guide
 
 When writing code, it is recommended to follow [LuaRocks's style guide], but using 2 space
 indentation to be consistent with the rest of PewPew's codebase.
 
-# Helpful tools and utilities
+## Helpful tools and utilities
 
 - [PewPew Snippets] is an essential Visual Studio Code extension that offers autocompletion and useful code snippets for creating levels.
 - [PewPewLive-MeshExporter] is a Blender plugin for converting scenes into PewPew Live 3D meshes.

diff --git a/docs/lua-guides/_category_.json b/docs/lua-guides/_category_.json
diff --git a/docs/other-guides/_category_.json b/docs/other-guides/_category_.json
diff --git a/docs/other/_category_.json b/docs/other/_category_.json
diff --git a/docusaurus.config.ts b/docusaurus.config.ts
@@ -1,42 +1,27 @@
-import { themes as prismThemes } from "prism-react-renderer"
-import type { Config } from "@docusaurus/types"
-import type * as Preset from "@docusaurus/preset-classic"
+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: "PPL Docs",
   tagline: "Documentation for PewPew Live",
   favicon: "img/favicon.ico",
-
-  // Set the production url of your site here
   url: "https://pewpewlive.github.io/",
-  // Set the /<baseUrl>/ pathname under which your site is served
-  // For GitHub pages deployment, it is often '/<projectName>/'
   baseUrl: "/ppl-docs/",
-
-  // GitHub pages deployment config.
-  // If you aren't using GitHub pages, you don't need these.
-  organizationName: "pewpewlive", // Usually your GitHub org/user name.
-  projectName: "docs", // Usually your repo name.
-
+  organizationName: "pewpewlive",
+  projectName: "docs",
   onBrokenLinks: "throw",
   onBrokenMarkdownLinks: "warn",
-
-  // Even if you don't use internationalization, you can use this field to set
-  // useful metadata like html lang. For example, if your site is Chinese, you
-  // may want to replace "en" with "zh-Hans".
   i18n: {
     defaultLocale: "en",
     locales: ["en"],
   },
-
   presets: [
     [
       "classic",
       {
         docs: {
           sidebarPath: "./sidebars.ts",
-          // Please change this to your repo.
-          // Remove this to remove the "edit this page" links.
           editUrl: "https://github.com/pewpewlive/ppl-docs/edit/master/",
         },
         blog: {
@@ -48,10 +33,7 @@ const config: Config = {
       } satisfies Preset.Options,
     ],
   ],
-
   themeConfig: {
-    // Replace with your project's social card
-    // image: "img/docusaurus-social-card.jpg",
     navbar: {
       title: "PPL Docs",
       logo: {
@@ -114,15 +96,18 @@ const config: Config = {
       ],
       copyright: `Copyright © ${new Date().getFullYear()} pewpewlive. Licensed under MIT. Built with Docusaurus.`,
     },
+    docs: {
+      sidebar: {
+        autoCollapseCategories: false,
+      },
+    },
     prism: {
-      theme: prismThemes.github,
-      darkTheme: prismThemes.dracula,
+      theme: prismThemes.oneDark,
+      darkTheme: prismThemes.oneDark,
       additionalLanguages: ["json", "lua"],
     },
   } satisfies Preset.ThemeConfig,
-  themes: [
-    require.resolve("@easyops-cn/docusaurus-search-local"),
-  ],
-}
+  themes: [require.resolve("@easyops-cn/docusaurus-search-local")],
+};
 
-export default config
+export default config;
diff --git a/sidebars.ts b/sidebars.ts
@@ -1,31 +1,7 @@
-import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
+import type { SidebarsConfig } from "@docusaurus/plugin-content-docs";
 
-/**
- * Creating a sidebar enables you to:
- - create an ordered group of docs
- - render a sidebar for each doc of that group
- - provide next/previous navigation
-
- The sidebars can be generated from the filesystem, or explicitly defined here.
-
- Create as many sidebars as you want.
- */
 const sidebars: SidebarsConfig = {
-  // By default, Docusaurus generates a sidebar from the docs folder structure
-  tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],
-
-  // But you can create a sidebar manually
-  /*
-  tutorialSidebar: [
-    'intro',
-    'hello',
-    {
-      type: 'category',
-      label: 'Tutorial',
-      items: ['tutorial-basics/create-a-document'],
-    },
-  ],
-   */
+  tutorialSidebar: [{ type: "autogenerated", dirName: "." }],
 };
 
 export default sidebars;