chore: revamped tutorial structure to be under feature groups

Author: darrenmelvison1

.github/scripts/aggregate-passport-metadata.js

@@ -7,6 +7,7 @@ const path = require('path');
 
 // Configuration
 const PASSPORT_ROOT = './sample/Assets/Scripts/Passport';
+const TUTORIALS_DIR = path.join(PASSPORT_ROOT, '_tutorials');
 const OUTPUT_DIR = './_parsed';
 const OUTPUT_FILE = path.join(OUTPUT_DIR, 'passport-features.json');
 const FEATURES_JSON_PATH = path.join(PASSPORT_ROOT, 'features.json');
@@ -23,138 +24,105 @@ try {
 
 console.log('Processing Passport features metadata...');
 
-// Load features.json to map script files to feature names
-const featuresMap = {};
+// Load features.json to get feature groups and their features
+let featureGroups = {};
 try {
   const featuresContent = fs.readFileSync(FEATURES_JSON_PATH, 'utf8');
   const featuresJson = JSON.parse(featuresContent);
-  
-  // Create mapping of script filename to feature name
-  featuresJson.features.forEach((feature) => {
-    const [featureName, scriptFile] = Object.entries(feature)[0];
-    // Store both the full filename and just the filename without path
-    featuresMap[scriptFile] = featureName;
-    featuresMap[path.basename(scriptFile)] = featureName;
-  });
+  featureGroups = featuresJson.features || {};
 } catch (error) {
   console.error(`Error reading features.json: ${error.message}`);
   process.exit(1);
 }
 
-// Platform-independent recursive file search
-const findMetadataFiles = () => {
-  const metadataFiles = [];
+// Find all feature group directories in _tutorials
+const findFeatureGroupDirectories = () => {
+  const featureGroupDirs = [];
+
+  if (!fs.existsSync(TUTORIALS_DIR)) {
+    console.warn(`Tutorials directory does not exist: ${TUTORIALS_DIR}`);
+    return featureGroupDirs;
+  }
 
-  const walkDir = (dir) => {
-    if (!fs.existsSync(dir)) {
-      console.warn(`Directory does not exist: ${dir}`);
-      return;
-    }
+  try {
+    const dirs = fs.readdirSync(TUTORIALS_DIR, { withFileTypes: true });
 
-    try {
-      const files = fs.readdirSync(dir);
-      
-      files.forEach((file) => {
-        const filePath = path.join(dir, file);
-        
-        try {
-          const stat = fs.statSync(filePath);
-          
-          if (stat.isDirectory()) {
-            walkDir(filePath);
-          } else if (file === 'metadata.json') {
-            metadataFiles.push(filePath);
-          }
-        } catch (err) {
-          console.warn(`Error accessing file ${filePath}: ${err.message}`);
-        }
-      });
-    } catch (err) {
-      console.warn(`Error reading directory ${dir}: ${err.message}`);
-    }
-  };
+    dirs.forEach((dirent) => {
+      if (dirent.isDirectory()) {
+        featureGroupDirs.push(path.join(TUTORIALS_DIR, dirent.name));
+      }
+    });
+  } catch (err) {
+    console.warn(`Error reading tutorials directory ${TUTORIALS_DIR}: ${err.message}`);
+  }
 
-  walkDir(PASSPORT_ROOT);
-  return metadataFiles;
+  return featureGroupDirs;
 };
 
 // Process metadata files
-const processMetadataFiles = (metadataFiles) => {
+const processFeatureGroups = (featureGroupDirs) => {
   const featuresObject = {};
 
-  metadataFiles.forEach((metadataFile) => {
-    console.log(`Processing ${metadataFile}`);
-    
-    // Extract feature directory
-    const featureDir = path.dirname(metadataFile);
+  featureGroupDirs.forEach((groupDir) => {
+    const groupName = path.basename(groupDir);
+    console.log(`Processing feature group: ${groupName}`);
 
-    // Get directory name as fallback feature name
-    const dirName = path.basename(featureDir);
+    // Check if this group exists in features.json
+    if (!featureGroups[groupName]) {
+      console.warn(`Feature group ${groupName} not found in features.json, skipping`);
+      return;
+    }
 
-    // Try to find feature name in feature map, fallback to directory name
-    let featureName = '';
-    try {
-      // Look for any script file in this directory
-      const dirFiles = fs.readdirSync(featureDir);
-      const scriptFiles = dirFiles.filter((file) => file.endsWith('.cs'));
-      
-      // Try to match any script file to our feature map
-      let found = false;
-      for (const scriptFile of scriptFiles) {
-        if (featuresMap[scriptFile]) {
-          featureName = featuresMap[scriptFile];
-          found = true;
-          break;
-        }
-      }
-      
-      if (!found) {
-        console.warn(`No feature found in features.json for ${featureDir}, using directory name`);
-        featureName = dirName;
-      }
-    } catch (error) {
-      console.warn(`Error processing directory ${featureDir}: ${error.message}`);
-      featureName = dirName;
+    // Path to metadata.json in this feature group directory
+    const metadataPath = path.join(groupDir, 'metadata.json');
+    if (!fs.existsSync(metadataPath)) {
+      console.warn(`No metadata.json found for feature group ${groupName} in ${groupDir}`);
+      return;
     }
 
-    // Create feature key (kebab-case)
-    const featureKey = featureName
+    // Path to tutorial.md in this feature group directory
+    const tutorialPath = path.join(groupDir, 'tutorial.md');
+    const tutorialExists = fs.existsSync(tutorialPath);
+    
+    // Create the feature key (kebab-case)
+    const featureKey = groupName
       .replace(/([a-z])([A-Z])/g, '$1-$2')
       .replace(/\s+/g, '-')
       .replace(/[^a-z0-9-]/gi, '')
       .toLowerCase();
 
     if (!featureKey) {
-      console.warn(`Generated empty feature key for ${featureDir}, skipping`);
+      console.warn(`Generated empty feature key for ${groupName}, skipping`);
       return;
     }
 
-    // Check for tutorial.md in the same directory
-    const tutorialPath = path.join(featureDir, 'tutorial.md');
-    const tutorialExists = fs.existsSync(tutorialPath);
     const tutorialFile = tutorialExists ? `${featureKey}.md` : null;
 
     if (!tutorialExists) {
-      console.warn(`No tutorial.md found for feature ${featureName} in ${featureDir}`);
+      console.warn(`No tutorial.md found for feature group ${groupName} in ${groupDir}`);
     }
 
     // Read and process metadata
     try {
-      const metadataContent = fs.readFileSync(metadataFile, 'utf8');
+      const metadataContent = fs.readFileSync(metadataPath, 'utf8');
       const metadata = JSON.parse(metadataContent);
 
       // Add additional fields
-      metadata.title = metadata.title || featureName;
+      metadata.title = metadata.title || groupName;
       metadata.sidebar_order = metadata.sidebar_order || 0;
       metadata.deprecated = metadata.deprecated || false;
 
+      // Add feature group information
+      metadata.feature_group = groupName;
+      metadata.features = Object.keys(featureGroups[groupName] || {});
+      
       // Create the feature entry
       featuresObject[featureKey] = {
         tutorial: tutorialFile,
         metadata: metadata
       };
     } catch (error) {
-      console.error(`Error processing metadata file ${metadataFile}: ${error.message}`);
+      console.error(`Error processing metadata file ${metadataPath}: ${error.message}`);
     }
   });
 
@@ -163,13 +131,13 @@ const processMetadataFiles = (metadataFiles) => {
 
 try {
   // Main execution
-  const metadataFiles = findMetadataFiles();
+  const featureGroupDirs = findFeatureGroupDirectories();
 
-  if (metadataFiles.length === 0) {
-    console.warn('No metadata files found. Output file will be empty.');
+  if (featureGroupDirs.length === 0) {
+    console.warn('No feature group directories found. Output file will be empty.');
   }
 
-  const features = processMetadataFiles(metadataFiles);
+  const features = processFeatureGroups(featureGroupDirs);
 
   // Create the final passport-features.json
   fs.writeFileSync(OUTPUT_FILE, JSON.stringify(features, null, 2));

.github/scripts/process-passport-tutorials.sh

@@ -8,57 +8,49 @@ DOCS_REPO_DIR="${CLONE_DIR:-"./imx-docs"}"
 
 # Root of the Passport features
 PASSPORT_ROOT="./sample/Assets/Scripts/Passport"
+TUTORIALS_DIR="${PASSPORT_ROOT}/_tutorials"
 
 echo "Processing Passport tutorials..."
 
-# Load features.json to map script files to feature names
+# Load features.json to get feature groups
 FEATURES_JSON="${PASSPORT_ROOT}/features.json"
 if [ ! -f "${FEATURES_JSON}" ]; then
   echo "Error: features.json not found at ${FEATURES_JSON}"
   exit 1
 fi
 
 # Create _tutorials directory in docs repo
-TUTORIALS_DIR="${DOCS_REPO_DIR}/docs/main/example/zkEVM/unity/passport-examples/_tutorials"
-mkdir -p "${TUTORIALS_DIR}"
+DOCS_TUTORIALS_DIR="${DOCS_REPO_DIR}/docs/main/example/zkEVM/unity/passport-examples/_tutorials"
+mkdir -p "${DOCS_TUTORIALS_DIR}"
 
-# Process null-delimited filenames
-find "${PASSPORT_ROOT}" -name "tutorial.md" -type f -print0 | while IFS= read -r -d '' TUTORIAL_FILE; do
-  echo "Processing ${TUTORIAL_FILE}"
-  
-  # Extract feature directory
-  FEATURE_DIR=$(dirname "${TUTORIAL_FILE}")
-  
-  # Try to find script file in this directory
-  SCRIPT_FILE=$(find "${FEATURE_DIR}" -name "*.cs" -type f -print0 | xargs -0 -n1 echo | head -n 1)
-  
-  if [ -z "${SCRIPT_FILE}" ]; then
-    echo "Warning: No script file found in ${FEATURE_DIR}, using directory name"
-    FEATURE_NAME=$(basename "${FEATURE_DIR}")
-  else
-    # Extract script filename
-    SCRIPT_FILENAME=$(basename "${SCRIPT_FILE}")
+# Check if _tutorials directory exists
+if [ ! -d "${TUTORIALS_DIR}" ]; then
+  echo "Warning: _tutorials directory not found at ${TUTORIALS_DIR}"
+else
+  # Process each feature group directory in _tutorials
+  find "${TUTORIALS_DIR}" -mindepth 1 -maxdepth 1 -type d -print0 | while IFS= read -r -d '' GROUP_DIR; do
+    echo "Processing feature group: ${GROUP_DIR}"
 
-    # Look up the feature name in features.json
-    # Extract feature name with error handling
-    if ! FEATURE_NAME=$(jq -r ".features[] | to_entries[] | select(.value == \"${SCRIPT_FILENAME}\") | .key" "${FEATURES_JSON}" 2>/dev/null); then
-      echo "Warning: Error parsing features.json with jq, using directory name"
-      FEATURE_NAME=$(basename "${FEATURE_DIR}")
-    fi
+    # Extract feature group name from directory
+    GROUP_NAME=$(basename "${GROUP_DIR}")
 
-    # If not found in features.json, fallback to directory name
-    if [ -z "${FEATURE_NAME}" ] || [ "${FEATURE_NAME}" == "null" ]; then
-      echo "Warning: Feature for script ${SCRIPT_FILENAME} not found in features.json, using directory name"
-      FEATURE_NAME=$(basename "${FEATURE_DIR}")
+    # Tutorial file path
+    TUTORIAL_FILE="${GROUP_DIR}/tutorial.md"
+    
+    if [ -f "${TUTORIAL_FILE}" ]; then
+      echo "Found tutorial for ${GROUP_NAME}"
+      
+      # Convert feature group name to kebab-case for the destination filename
+      KEBAB_NAME=$(echo "${GROUP_NAME}" | sed -E 's/([a-z])([A-Z])/\1-\2/g' | tr '[:upper:]' '[:lower:]')
+      
+      # Copy the tutorial file
+      cp "${TUTORIAL_FILE}" "${DOCS_TUTORIALS_DIR}/${KEBAB_NAME}.md"
+      echo "Copied ${TUTORIAL_FILE} to ${DOCS_TUTORIALS_DIR}/${KEBAB_NAME}.md"
+    else
+      echo "Warning: No tutorial.md found for feature group ${GROUP_NAME}"
     fi
-  fi
-  
-  echo "Feature name: ${FEATURE_NAME}"
-  
-  # Copy and rename tutorial file
-  cp "${TUTORIAL_FILE}" "${TUTORIALS_DIR}/${FEATURE_NAME}.md"
-  echo "Copied ${TUTORIAL_FILE} to ${TUTORIALS_DIR}/${FEATURE_NAME}.md"
-done
+  done
+fi
 
 # Copy the generated JSON file
 JSON_FILE="./_parsed/passport-features.json"

.github/workflows/publish-passport-tutorials.yml

@@ -7,9 +7,8 @@ on:
       # - main
       - chore/sample-app-tutorial
     paths:
-      - 'sample/Assets/Scripts/Passport/**/tutorial.md'
-      - 'sample/Assets/Scripts/Passport/**/metadata.json'
       - 'sample/Assets/Scripts/Passport/features.json'
+      - 'sample/Assets/Scripts/Passport/_tutorials/**/*'
 
   # Allow manual triggering
   workflow_dispatch: