add code examples to classes, as reusable component

Author: Fernando-A-Rocha

TODO.txt

@@ -0,0 +1,3 @@
+- Generate pages with list of OOP functions by Element type for server and client
+https://wiki.multitheftauto.com/wiki/OOP_server
+https://wiki.multitheftauto.com/wiki/OOP_client

classes/Matrix/Matrix.yaml

@@ -2,3 +2,13 @@ name: 'matrix'
 description: |
   Matrices are one of the most powerful features of MTA [OOP](/OOP). We did have a presence of Matrices before with [getElementMatrix](/getElementMatrix), but we were given an ugly disgusting table to play with. Now, with the new Matrix class, we can make and magically manipulate Matrices.
 
+examples:
+  - path: examples/matrix-1.lua
+    description: >
+      Say you wanted to create a bin - object 1337 - two units in front of a player. You don't want to manually do trigonometry and you don't want to play with the complicated tables. You just want to get the position two units in front of the player whilst taking into account the rotation of the player. You only need to use Matrix.getForward, Matrix.getPosition and getElementMatrix. It's just:
+  - path: examples/matrix-2.lua
+    description: >
+      If you wanted the opposite of matrix.forward you'll still use matrix.forward but you minus it instead of matrix.backward which doesn't exist. Same applies with matrix.right and matrix.up. To make the bin object appear behind a player:
+  - path: examples/matrix-3.lua
+    description: >
+      Say you'd like to get find the position underneath a vehicle. This is the position at any rotation. So if it was upside down, the Z value would be higher than the vehicle Z value. If the vehicle was the right way round, the Z value for underneath car would be less than the Z value for the car.

classes/Matrix/examples/matrix-1.lua

@@ -0,0 +1 @@
+Object ( 1337, player.matrix.position + player.matrix.forward * 2 )

classes/Matrix/examples/matrix-2.lua

@@ -0,0 +1 @@
+Object ( 1337, player.matrix.position - player.matrix.forward * 2 )

classes/Matrix/examples/matrix-3.lua

@@ -0,0 +1,15 @@
+--
+-- Instead of:
+--
+local matrix = getElementMatrix(vehicle)
+local offX = 0 * matrix[1][1] + 0 * matrix[2][1] - 1 * matrix[3][1] + matrix[4][1]
+local offY = 0 * matrix[1][2] + 0 * matrix[2][2] - 1 * matrix[3][2] + matrix[4][2]
+local offZ = 0 * matrix[1][3] + 0 * matrix[2][3] - 1 * matrix[3][3] + matrix[4][3]
+
+local pX, pY, pZ = getElementPosition(vehicle)
+local positionBelow = {offX-pX, offY-pY, offZ-pZ}
+
+--
+-- You only have to do:
+--
+local positionBelow = vehicle.position - vehicle.matrix.up

schemas/class.yaml

@@ -12,5 +12,7 @@ properties:
   description:
     type: string
     description: Description of the OOP class.
+  examples:
+    $ref: 'common-defs.yaml#/$defs/examples'
   see_also:
     $ref: 'common-defs.yaml#/$defs/see_also'

web/src/components/CodeExamplesSection.astro

@@ -0,0 +1,29 @@
+---
+import { Code } from '@astrojs/starlight/components';
+import { marked } from 'marked';
+
+export interface CodeExample {
+  description?: string;
+  luaCode: string;
+}
+
+export interface Props {
+  codeExamples: CodeExample[];
+}
+
+const { codeExamples } = Astro.props;
+---
+
+{codeExamples.length > 0 && (
+  <div class="examples-section">
+    <h4>Code Examples</h4>
+    {codeExamples.map((example) => (
+      <div class="function-example">
+        {example.description && (
+          <Fragment set:html={marked(example.description)} />
+        )}
+        <Code code={example.luaCode} lang="lua" />
+      </div>
+    ))}
+  </div>
+)}

web/src/pages/[event].astro

@@ -12,6 +12,7 @@ import NoteBox from '@src/components/NoteBox.astro';
 import type { NotesType } from '@src/utils/types';
 
 import SeeAlsoSection from '@src/components/SeeAlsoSection.astro';
+import CodeExamplesSection from '@src/components/CodeExamplesSection.astro';
 
 export async function getStaticPaths() {
     const events = await getCollection('events');
@@ -105,19 +106,7 @@ if (Array.isArray(event.data.notes) && event.data.notes.length > 0) {
             `addEventHandler("${event.id}", elementAttachedTo, ${eventHandlerExample.funcName})`
         } lang="lua" />
 
-        {eventExamples.length > 0 && (
-            <div class="examples-section">
-                <h4>Code Examples</h4>
-                {eventExamples.map((example: any) => (
-                    <div class="function-example">
-                        {example.description && (
-                            <Fragment set:html={marked(example.description)} />
-                        )}
-                        <Code code={example.luaCode} lang="lua"/>
-                    </div>
-                ))}
-            </div>
-        )}
+        <CodeExamplesSection codeExamples={eventExamples} />
 
         <SeeAlsoSection seeAlsoLinks={getSeeAlsoLinksForItem(event)} currentId={event.id} />
     </StarlightPage>

web/src/pages/[func].astro

@@ -13,6 +13,7 @@ import '@src/styles/function-page.css';
 import type { NotesType } from '@src/utils/types';
 
 import SeeAlsoSection from '@src/components/SeeAlsoSection.astro';
+import CodeExamplesSection from '@src/components/CodeExamplesSection.astro';
 
 export async function getStaticPaths() {
     const functions = await getCollection('functions');
@@ -171,20 +172,7 @@ let funcSyntaxes = parseFunctionSyntaxes(func.id, func.data);
             </div>
         ))}
 
-        <!-- Examples -->
-        {funcExamples.length > 0 && (
-            <div class="examples-section">
-                 <h4>Code Examples</h4>
-                 {funcExamples.map((example: any) => (
-                    <div class="function-example">
-                        {example.description && (
-                            <Fragment set:html={marked(example.description)} />
-                        )}
-                        <Code code={example.luaCode} lang="lua"/>
-                    </div>
-                ))}
-            </div>
-        )}
+        <CodeExamplesSection codeExamples={funcExamples} />
 
         <SeeAlsoSection seeAlsoLinks={getSeeAlsoLinksForItem(func)} currentId={func.id} />
     </StarlightPage>

web/src/pages/[oopclass].astro

@@ -2,9 +2,12 @@
 import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
 import { getCollection } from 'astro:content';
 import { marked } from 'marked';
+import fs from "fs";
+import path from "path";
 import { getSeeAlsoLinksForItem } from '@src/utils/general';
 
 import SeeAlsoSection from '@src/components/SeeAlsoSection.astro';
+import CodeExamplesSection from '@src/components/CodeExamplesSection.astro';
 
 export async function getStaticPaths() {
   const classes = await getCollection('classes');
@@ -16,6 +19,18 @@ export async function getStaticPaths() {
 
 const { oopclass } = Astro.props;
 oopclass.data.itemType = 'class';
+const oopClassPath = path.dirname(oopclass.filePath ?? "");
+
+let codeExamples: any[] = oopclass.data.examples || [];
+codeExamples = codeExamples.map((example: any) => {
+    try {
+        const luaCode = fs.readFileSync(path.resolve(`${oopClassPath}`, example.path), "utf8"); 
+        return { ...example, luaCode };
+    } catch (error) {
+        console.error(`Error reading ${example.path}:`, error);
+        return { ...example, luaCode: "Loading example error." };
+    }
+});
 
 ---
 <StarlightPage frontmatter={{
@@ -25,6 +40,8 @@ oopclass.data.itemType = 'class';
 }}>
   <Fragment set:html={marked(oopclass.data.description)} />
 
+  <CodeExamplesSection codeExamples={codeExamples} />
+
   <SeeAlsoSection seeAlsoLinks={getSeeAlsoLinksForItem(oopclass)} currentId={oopclass.id} />
 </StarlightPage>