Merge branch 'docs/new-features'

Author: Lettify

schemas/function.yaml

@@ -43,6 +43,14 @@ $defs:
       description:
         type: string
         description: Describes the functionality provided by the function.
+      important_notes:
+        type: array
+        description: |
+          A list of important notes about the function.
+          This is a list of things that are important to know about the function, but not
+          necessarily related to the function itself.
+        items:
+          type: string
       notes:
         type: array
         description: List of noteworthy pieces of information for the function.

web/src/components/NoteBox.astro

@@ -0,0 +1,19 @@
+---
+---
+<div class="custom-note-box">
+    <slot />
+</div >
+
+<style>
+.custom-note-box {
+    background-color: var(--sl-color-blue-low);
+    border-left: 4px solid var(--sl-color-blue);
+    border-radius: 8px;
+    padding: 1rem 1.25rem;
+    margin-bottom: 1rem;
+    color: var(--sl-color-text);
+}
+html[data-theme="dark"] .custom-note-box {
+    background-color: var(--sl-color-gray-5);
+}
+</style>

web/src/pages/[func].astro

@@ -7,6 +7,9 @@ import fs from "fs";
 import path from "path";
 import { Code } from '@astrojs/starlight/components';
 
+import NoteBox from '@src/components/NoteBox.astro';
+import '@src/styles/function-page.css';
+
 export async function getStaticPaths() {
     const functions = await getCollection('functions');
     return functions.map(func => ({
@@ -19,24 +22,30 @@ const { func } = Astro.props;
 
 const funcInfo = getFunctionInfo(func.data);
 const funcType = funcInfo.type;
-const funcTypePretty = funcInfo.typePretty;
-
 const funcPair = funcInfo.pair;
-const funcPath = path.dirname(func.filePath ?? "")
-let funcExamples = funcInfo.examples
+const funcPath = path.dirname(func.filePath ?? "");
 
-if ( funcExamples.length > 0 ){
-    funcExamples = funcInfo.examples.map((example: any) => {
+const { description, notes: funcNotes, examples: rawExamples } = funcInfo;
+
+let processedExamples: any[] = [];
+if (Array.isArray(rawExamples) && rawExamples.length > 0) {
+    processedExamples = rawExamples.map((example: any) => {
         try {
-            const luaCode = fs.readFileSync(path.resolve(`${funcPath}`, example.path), "utf8"); 
+            const exampleFilePath = path.resolve(funcPath, example.path);
+            const luaCode = fs.readFileSync(exampleFilePath, "utf8");
             return { ...example, luaCode };
         } catch (error) {
-            console.error(`Error reading ${example.path}:`, error);
-            return { ...example, luaCode: "Loading example error." };
+            console.error(`Error reading example file ${example.path} at ${path.resolve(funcPath, example.path)}:`, error);
+            return { ...example, luaCode: `Error loading example: ${example.path}` };
         }
     });
 }
 
+let notesContent: string[] = [];
+if (Array.isArray(funcNotes) && funcNotes.length > 0) {
+    notesContent = funcNotes;
+}
+
 ---
 
 <div class={"show-type-badge-" + funcType}>
@@ -45,18 +54,34 @@ if ( funcExamples.length > 0 ){
         title: func.id,
         tableOfContents: false,
     }}>
+        <!-- Pair Function Ref -->
         {funcPair && (
             <p><strong>Pair:</strong> <a href={ `/${funcPair}` }>{ funcPair }</a></p>
         )}
 
         <!-- Description -->
-        <Fragment set:html={marked(funcInfo.description)} />
+        {description && <Fragment set:html={marked(description)} />}
+
+        <!-- Notes -->
+        <div class="notes-section">
+            {notesContent.map((note) => (
+                <NoteBox>
+                    <Fragment set:html={marked(note)} />
+                </NoteBox>
+            ))}
+        </div>
 
-        {funcExamples.length > 0 && funcExamples.map((example: any) => (
-            <div>
-                <p set:html={marked(example.description)}></p>
-                <Code code={example.luaCode} lang="lua" title={path.basename(example.path)} />
+        <!-- Examples -->
+        {processedExamples.length > 0 && (
+            <div class="examples-section">
+                 <h3>Exemplos</h3>
+                 {processedExamples.map((example: any) => (
+                    <div class="function-example">
+                        <Fragment set:html={marked(example.description)} />
+                        <Code code={example.luaCode} lang="lua" title={path.basename(example.path)} />
+                    </div>
+                ))}
             </div>
-        ))}
+        )}
     </StarlightPage>
 </div>

web/src/styles/function-page.css

@@ -0,0 +1,26 @@
+.function-syntax,
+.function-oop,
+.notes-section,
+.examples-section {
+    margin-top: 1.5rem;
+    margin-bottom: 1.5rem;
+}
+
+.function-syntax h3,
+.function-oop h3,
+.examples-section h3 {
+    margin-bottom: 0.75rem;
+    font-size: 1.25em;
+    border-bottom: 1px solid var(--sl-color-gray-5);
+    padding-bottom: 0.25rem;
+}
+
+.function-example {
+    margin-bottom: 1.5rem;
+}
+.function-example > :first-child {
+    margin-bottom: 0.5rem;
+}
+.examples-section .function-example:last-child {
+    margin-bottom: 0;
+}

web/src/utils/functions.ts

@@ -8,7 +8,7 @@ type FunctionItem = Awaited<ReturnType<typeof getCollection>>[number];
 // Define a structure for function parameters
 type FunctionParameter = {
     name: string;
-    type: string; // Adjust type as needed (e.g., string | string[])
+    type: string;
     description?: string;
     optional?: boolean;
 };
@@ -19,6 +19,7 @@ type FunctionDetails = {
     pair?: boolean;
     examples?: { code: string; description?: string }[];
     notes?: string[];
+    important_notes?: string[];
     parameters?: FunctionParameter[];
 };
 
@@ -36,7 +37,6 @@ export type FunctionData = {
     server?: any;
 };
 
-// Use the specific FunctionDetails type
 export type TypedFunctionData = {
     shared?: FunctionDetails;
     client?: FunctionDetails;
@@ -47,42 +47,42 @@ export const functionTypePrettyName = {
     'client': 'Client-side',
     'server': 'Server-side',
     'shared': 'Shared',
-} as const; // Use 'as const' for stricter typing of keys
+} as const;
 
 function getFunctionType(data: FunctionData): FunctionType {
     if (data.shared) return 'shared';
     if (data.client) return 'client';
     return 'server';
 }
 function getFunctionTypePretty(data: FunctionData): string {
-    // No need for fallback, getFunctionType guarantees a valid FunctionType
     const funcType = getFunctionType(data);
     return functionTypePrettyName[funcType];
 }
 
-// Define a return type for getFunctionInfo
 export type FunctionInfo = {
     description: string;
     type: FunctionType;
     typePretty: string;
     pair: boolean;
     examples: { code: string; description?: string }[];
-    notes?: string[]; // Added notes
-    parameters?: FunctionParameter[]; // Added parameters
+    notes?: string[];
+    important_notes?: string[];
+    parameters?: FunctionParameter[];
 };
 
 export function getFunctionInfo(data: TypedFunctionData): FunctionInfo {
     const type = getFunctionType(data);
-    const details = data[type] ?? {}; // Get details based on type, default to empty object
+    const details = data[type] ?? {};
 
     return {
         description: details.description || '',
         type: type,
         typePretty: getFunctionTypePretty(data),
         pair: details.pair || false,
         examples: details.examples || [],
-        notes: details.notes, // Extract notes (will be undefined if not present)
-        parameters: details.parameters || [], // Extract parameters
+        notes: details.notes || [],
+        important_notes: details.important_notes || [],
+        parameters: details.parameters || [],
     };
 }
 
@@ -95,16 +95,14 @@ let functionsByTypeByCategory: FunctionsByTypeByCategory = {
 };
 
 for (let func of functionsCollection) {
-    // Assuming func.filePath exists, handle potential undefined if necessary
-    const normalizedPath = path.normalize(func.id); // Use func.id which includes the path relative to content dir
+    const normalizedPath = path.normalize(func.id);
     const folder = path.basename(path.dirname(normalizedPath));
     if (!functionsByCategory[folder]) {
         functionsByCategory[folder] = [];
     }
     functionsByCategory[folder].push(func);
 
     const funcType = getFunctionType(func.data);
-    // Ensure the folder exists for the specific type
     if (!functionsByTypeByCategory[funcType]?.[folder]) {
         functionsByTypeByCategory[funcType][folder] = [];
     }