Update PR template and improve example validator script

.github/pull_request_template.md

@@ -1,62 +1,62 @@
 # Description
-
-_Please include a summary of the changes and the related issue. Please also include relevant
-motivation and context. List any dependencies that are required for this change._
+Please include a summary of the changes and the related issue. Please also include relevant motivation and context. List any dependencies that are required for this change.
 
 ## Type of change
-
-_Please delete options that are not relevant._
+Please delete options that are not relevant.
 
 - [ ] Bug fix (non-breaking change which fixes an issue)
 - [ ] New feature (non-breaking change which adds functionality)
-- [ ] Breaking change (fix or feature that would cause existing functionality to not work as
-      expected)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
 - [ ] Documentation (update or new)
 
 ## How Has This Been Tested?
+Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also list any relevant details for your test configuration.
 
-_Please describe the tests that you ran to verify your changes. Provide instructions so we can
-reproduce. Please also list any relevant details for your test configuration._
-
-## Testing Checklist
-
+### Testing Checklist
 - [ ] Tested in latest Chrome
 - [ ] Tested in latest Firefox
-- [ ] npm run build
-- [ ] npm run preview
+- [ ] `npm run build`
+- [ ] `npm run preview`
 
 ## Checklist
-
-_Please delete options that are not relevant._
+Please delete options that are not relevant.
 
 ### If involving code
-
 - [ ] My code follows the style guidelines of this project
 - [ ] I have performed a self-review of my own code
 - [ ] I have commented my code in hard-to-understand areas
 - [ ] I have made corresponding changes to the documentation
 - [ ] My changes generate no new warnings
 
 ### If modified config files
-
 - [ ] I have checked the following files for changes:
-  - [ ] package.json
-  - [ ] astro.config.mjs
-  - [ ] netlify.toml
-  - [ ] docker-compose.yml
-  - [ ] custom.css
+    - [ ] package.json
+    - [ ] astro.config.mjs
+    - [ ] netlify.toml
+    - [ ] docker-compose.yml
+    - [ ] custom.css
 
 ## Folders and Files Added/Modified
+Please list the folders and files added/modified with this pull request and delete options that are not relevant.
 
-_Please list the folders and files added/modified with this pull request and delete options that are not relevant._
+### Added:
+- folder/folder
+- folder/folder
 
-- Added:
-  - [ ] folder/folder
-  - [ ] folder/folder
-- Modified:
-  - [ ] folder/file
-  - [ ] folder/file
+### Modified:
+- folder/file
+- folder/file
 
 ## Additional Notes
+Please add any additional information that might be useful for the reviewers.
+
+---
+
+### Geometry Example Validation (Optional)
+<!-- 
+To validate a single geometry example:
+node ./scripts/usage-examples-testing-script.cjs <example_key>
 
-_Please add any additional information that might be useful for the reviewers._
+To validate all geometry examples (PowerShell):
+$dir = "public/usage-examples/geometry"; $examples = Get-ChildItem -Path $dir -Filter "*-example.txt" | Select-Object -ExpandProperty BaseName | Sort-Object -Unique; if (-not $examples) { Write-Error "No *-example.txt files found in $dir"; exit 1 }; $failed = @(); foreach ($ex in $examples) { Write-Host "`n=== Validating $ex ==="; node .\scripts\usage-examples-testing-script.cjs $ex; if ($LASTEXITCODE -ne 0) { $failed += $ex } }; if ($failed.Count -gt 0) { Write-Host "`nFAILED examples:"; $failed | ForEach-Object { Write-Host " - $_" }; exit 1 } else { Write-Host "`nAll Geometry examples validated successfully: $($examples.Count)" }
+-->

scripts/api-pages-script.cjs

@@ -134,6 +134,8 @@ function getAllFinishedExamples() {
 // ------------------------------------------------------------------------------
 // Type Mappings
 // ------------------------------------------------------------------------------
+const globalFunctionGroups = {};
+
 function Mappings(jsonData) {
   //generate mappings from API
   for (const categoryKey in jsonData) {
@@ -312,10 +314,11 @@ function getGroupName(jsonData, uniqueName) {
     const category = jsonData[categoryKey];
     const categoryFunctions = category.functions;
     categoryFunctions.forEach((func) => {
-      if (func.unique_global_name == uniqueName) {
-        funcGroupName = func.name.split("_").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");;
+      if (func.unique_global_name == uniqueName || func.name == uniqueName) {
+        funcGroupName = func.name.split("_").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
       }
     });
+    if (funcGroupName) break;
   }
   return funcGroupName;
 }
@@ -480,6 +483,18 @@ let mdxContent = "";
 let success = true;
 const jsonData = getJsonData("api.json");
 const jsonColors = getJsonData("colors.json");
+
+// Pre-calculate global function counts after jsonData is loaded
+for (const categoryKey in jsonData) {
+  if (categoryKey !== "types") {
+    jsonData[categoryKey].functions.forEach((f) => {
+      if (!globalFunctionGroups[f.name]) {
+        globalFunctionGroups[f.name] = 0;
+      }
+      globalFunctionGroups[f.name]++;
+    });
+  }
+}
 let guidesJson = getJsonData("guides.json");
 let usageExamplesJson = getJsonData("usage-example-references.json");
 let guidesCategories = getApiCategories(guidesJson);
@@ -642,7 +657,7 @@ for (const categoryKey in jsonData) {
       // Put {</>} symbol at the end of headers of overloaded functions with usage example or else just keep empty
       const formattedName = isOverloaded
         ? `\n#### [${functionName2}](#${formattedUniqueLink})${hasSymbol} \\{#${formattedUniqueLink}\\}`
-        : `\n### [${functionName2}](#${formattedLink})${hasSymbol}`;
+        : `\n### [${functionName2}](#${formattedLink})${hasSymbol} \\{#${formattedLink}\\}`;
 
       // Replace type names in the description with formatted versions
       let description = func.description || "";
@@ -672,8 +687,11 @@ for (const categoryKey in jsonData) {
           .split("_")
           .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
           .join(" ");
-        const formattedLink = normalName.toLowerCase().replace(/\s+/g, "-");
-        const link = `[\`${normalName}\`](/api/${input}/#${formattedLink})`
+        let formattedLink = normalName.toLowerCase().replace(/\s+/g, "-");
+        if (functionGroups[names] && functionGroups[names].length > 1) {
+          formattedLink += "-functions";
+        }
+        const link = `[\`${normalName}\`](/api/${input}/#${formattedLink})`;
         description = description.replace(new RegExp(`\`\\b${names}\\b\``, "g"), link);
         description = description.replaceAll("\n", " ");
       }
@@ -709,8 +727,11 @@ for (const categoryKey in jsonData) {
               .split("_")
               .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
               .join(" ");
-            const formattedLink = normalName.toLowerCase().replace(/\s+/g, "-");
-            const link = `[\`${normalName}\`](/api/${input}/#${formattedLink})`
+            let formattedLink = normalName.toLowerCase().replace(/\s+/g, "-");
+            if (functionGroups[names] && functionGroups[names].length > 1) {
+              formattedLink += "-functions";
+            }
+            const link = `[\`${normalName}\`](/api/${input}/#${formattedLink})`;
             description2 = description2.replace(new RegExp(`\`\\b${names}\\b\``, "g"), link);
             description2 = description2.replaceAll("\n", " ");
           }
@@ -738,6 +759,20 @@ for (const categoryKey in jsonData) {
           );
         }
 
+        for (const names of functionNames) {
+          const normalName = names
+            .split("_")
+            .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+            .join(" ");
+          let formattedLink = normalName.toLowerCase().replace(/\s+/g, "-");
+          if (functionGroups[names] && functionGroups[names].length > 1) {
+            formattedLink += "-functions";
+          }
+          const link = `[\`${normalName}\`](/api/${input}/#${formattedLink})`;
+          returnDescription = returnDescription.replace(new RegExp(`\`\\b${names}\\b\``, "g"), link);
+          returnDescription = returnDescription.replaceAll("\n", " ");
+        }
+
         mdxContent += `${returnDescription}\n\n`;
       }
 
@@ -785,7 +820,7 @@ for (const categoryKey in jsonData) {
           example.functions.forEach((used) => {
             if (func.unique_global_name == used && limit < 4) {
               allExamples.push({
-                name: example.funcKey,
+                funcKey: example.funcKey,
                 title: example.title,
                 url: example.url
               })
@@ -814,8 +849,19 @@ for (const categoryKey in jsonData) {
         if (allExamples.length > 0) {
           mdxContent += `**API Documentation Code Examples**:\n\n`
           allExamples.forEach((example) => {
-            const exampleName = getGroupName(jsonData, example.name);
-            mdxContent += `- [${exampleName}](${example.url}): ${example.title}\n`
+            let exampleName = getGroupName(jsonData, example.funcKey);
+            if (exampleName == "" && example.funcKey) {
+              exampleName = example.funcKey.split("_").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+            }
+            if (exampleName == "") exampleName = "Example";
+
+            let exampleUrl = example.url;
+            if (example.funcKey && globalFunctionGroups[example.funcKey] > 1) {
+              const hash = example.funcKey.toLowerCase().replace(/_/g, "-");
+              exampleUrl = exampleUrl.replace(/#.*$/, `#${hash}-functions`);
+            }
+
+            mdxContent += `- [${exampleName}](${exampleUrl}): ${example.title}\n`
           })
         }
 
@@ -887,8 +933,11 @@ for (const categoryKey in jsonData) {
             .split("_")
             .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
             .join(" ");
-          const formattedLink = normalName.toLowerCase().replace(/\s+/g, "-");
-          const link = `[\`${normalName}\`](/api/${input}/#${formattedLink})`
+          let formattedLink = normalName.toLowerCase().replace(/\s+/g, "-");
+          if (functionGroups[names] && functionGroups[names].length > 1) {
+            formattedLink += "-functions";
+          }
+          const link = `[\`${normalName}\`](/api/${input}/#${formattedLink})`;
 
           description = description.replace(new RegExp(`\`\\b${names}\\b\``, "g"), link);
         }
@@ -917,9 +966,12 @@ for (const categoryKey in jsonData) {
                 .split("_")
                 .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
                 .join(" ");
-              const formattedLink = normalName.toLowerCase().replace(/\s+/g, "-");
-              const link = `[\`${normalName}\`](/api/${input}/#${formattedLink})`
-              description = description.replace(new RegExp(`\`\\b${names}\\b\``, "g"), link);
+              let formattedLink = normalName.toLowerCase().replace(/\s+/g, "-");
+              if (functionGroups[names] && functionGroups[names].length > 1) {
+                formattedLink += "-functions";
+              }
+              const link = `[\`${normalName}\`](/api/${input}/#${formattedLink})`;
+              fieldDescription = fieldDescription.replace(new RegExp(`\`\\b${names}\\b\``, "g"), link);
             }
 
             mdxContent += `| ${fieldName} | ${fieldType} | ${fieldDescription.replace(/\n/g, '')} |\n`;
@@ -937,8 +989,11 @@ for (const categoryKey in jsonData) {
             .split("_")
             .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
             .join(" ");
-          const formattedLink = normalName.toLowerCase().replace(/\s+/g, "-");
-          const link = `[\`${normalName}\`](/api/${input}/#${formattedLink})`
+          let formattedLink = normalName.toLowerCase().replace(/\s+/g, "-");
+          if (functionGroups[names] && functionGroups[names].length > 1) {
+            formattedLink += "-functions";
+          }
+          const link = `[\`${normalName}\`](/api/${input}/#${formattedLink})`;
           description = description.replace(new RegExp(`\`\\b${names}\\b\``, "g"), link);
         }
         description = description.replaceAll("\n\n\n", "\n\n");