docs: Document doctree export and WARP guidelines

- Add documentation for doctree export functionality
- Include WARP.md with project guidelines and commands

aiprompts/WARP.md

@@ -5,12 +5,15 @@ This file provides guidance to WARP (warp.dev) when working with code in this re
 ## Commands to Use
 
 ### Testing
+
 - **Run Tests**: Utilize `vtest ~/code/github/incubaid/herolib/lib/osal/package_test.v` to run specific tests.
 
 ## High-Level Architecture
+
 - **Project Structure**: The project is organized into multiple modules located in `lib` and `src` directories. Prioritized compilation and caching strategies are utilized across modules.
 - **Script Handling**: Vlang scripts are crucial and should follow instructions from `aiprompts/vlang_herolib_core.md`.
 
 ## Special Instructions
+
 - **Documentation Reference**: Always refer to `aiprompts/vlang_herolib_core.md` for essential instructions regarding Vlang and Heroscript code generation and execution.
 - **Environment Specifics**: Ensure Redis and other dependencies are configured as per scripts provided in the codebase.

aiprompts/doctree/doctree_specs.md

@@ -1,36 +1,41 @@
 # Doctree Export Specification
 
 ## Overview
+
 The `doctree` module in `lib/data/doctree` is responsible for processing and exporting documentation trees. This involves taking a structured representation of documentation (collections, pages, images, files) and writing it to a specified file system destination. Additionally, it leverages Redis to store metadata about the exported documentation, facilitating quick lookups and integration with other systems.
 
 ## Key Components
 
 ### `lib/data/doctree/export.v`
+
 This file defines the main `export` function for the `Tree` object. It orchestrates the overall export process:
+
 - Takes `TreeExportArgs` which includes parameters like `destination`, `reset` (to clear destination), `keep_structure`, `exclude_errors`, `toreplace` (for regex replacements), `concurrent` (for parallel processing), and `redis` (to control Redis metadata storage).
 - Processes definitions, includes, actions, and macros within the `Tree`.
 - Generates file paths for pages, images, and other files.
 - Iterates through `Collection` objects within the `Tree` and calls their respective `export` methods, passing down the `redis` flag.
 
 ### `lib/data/doctree/collection/export.v`
+
 This file defines the `export` function for the `Collection` object. This is where the actual file system writing and Redis interaction for individual collections occur:
+
 - Takes `CollectionExportArgs` which includes `destination`, `file_paths`, `reset`, `keep_structure`, `exclude_errors`, `replacer`, and the `redis` flag.
 - Creates a `.collection` file in the destination directory with basic collection information.
 - **Redis Integration**:
-    - Obtains a Redis client using `base.context().redis()`.
+  - Obtains a Redis client using `base.context().redis()`.
-    - Stores the collection's destination path in Redis using `redis.hset('doctree:path', 'collection_name', 'destination_path')`.
+  - Stores the collection's destination path in Redis using `redis.hset('doctree:path', 'collection_name', 'destination_path')`.
-    - Calls `export_pages`, `export_files`, `export_images`, and `export_linked_pages` which all interact with Redis if the `redis` flag is true.
+  - Calls `export_pages`, `export_files`, `export_images`, and `export_linked_pages` which all interact with Redis if the `redis` flag is true.
 - **`export_pages`**:
-    - Processes page links and handles not-found errors.
+  - Processes page links and handles not-found errors.
-    - Writes markdown content to the destination file system.
+  - Writes markdown content to the destination file system.
-    - Stores page metadata in Redis: `redis.hset('doctree:collection_name', 'page_name', 'page_file_name.md')`.
+  - Stores page metadata in Redis: `redis.hset('doctree:collection_name', 'page_name', 'page_file_name.md')`.
 - **`export_files` and `export_images`**:
-    - Copies files and images to the destination directory (e.g., `img/`).
+  - Copies files and images to the destination directory (e.g., `img/`).
-    - Stores file/image metadata in Redis: `redis.hset('doctree:collection_name', 'file_name', 'img/file_name.ext')`.
+  - Stores file/image metadata in Redis: `redis.hset('doctree:collection_name', 'file_name', 'img/file_name.ext')`.
 - **`export_linked_pages`**:
-    - Gathers linked pages within the collection.
+  - Gathers linked pages within the collection.
-    - Writes a `.linkedpages` file.
+  - Writes a `.linkedpages` file.
-    - Stores linked pages file metadata in Redis: `redis.hset('doctree:collection_name', 'linkedpages', 'linkedpages_file_name.md')`.
+  - Stores linked pages file metadata in Redis: `redis.hset('doctree:collection_name', 'linkedpages', 'linkedpages_file_name.md')`.
 
 ## Link between Redis and Export
 
@@ -43,4 +48,4 @@ This Redis integration serves as a quick lookup mechanism for other applications
 Yes, the export functionality is crucial for making the processed `doctree` content available outside the internal `doctree` representation.
 
 - **File System Export**: The core purpose of the export is to write the documentation content (markdown files, images, other assets) to a specified directory. This is essential for serving the documentation via a web server, integrating with static site generators (like Docusaurus, as suggested by other files in the project), or simply providing a browsable version of the documentation.
-- **Redis Metadata**: While the file system export is fundamental, the Redis metadata storage is an important complementary feature. It provides an efficient way for other systems to programmatically discover and locate documentation assets. If there are downstream applications that rely on this Redis metadata for navigation, search, or content delivery, then the Redis part of the export is indeed needed. If no such applications exist or are planned, the `redis` flag can be set to `false` to skip this step, but the file system export itself remains necessary for external consumption of the documentation.
+- **Redis Metadata**: While the file system export is fundamental, the Redis metadata storage is an important complementary feature. It provides an efficient way for other systems to programmatically discover and locate documentation assets. If there are downstream applications that rely on this Redis metadata for navigation, search, or content delivery, then the Redis part of the export is indeed needed. If no such applications exist or are planned, the `redis` flag can be set to `false` to skip this step, but the file system export itself remains necessary for external consumption of the documentation.

release_OLD.sh

@@ -1,109 +0,0 @@
-#!/usr/bin/env bash
-
-# Exit on error
-set -e
-
-# Function to get the latest release from GitHub
-get_latest_release() {
-    local url="https://api.github.com/repos/incubaid/herolib/releases/latest"
-    local response
-    response=$(curl -s "$url")
-    if [ $? -ne 0 ]; then
-        echo "Error: Failed to fetch from GitHub API" >&2
-        exit 1
-    fi
-    
-    # Extract tag_name using grep and cut
-    echo "$response" | grep -o '"tag_name":"[^"]*' | cut -d'"' -f4
-}
-
-# Show current version
-latest_release=$(get_latest_release)
-if [ -z "$latest_release" ]; then
-    echo "Error getting latest release" >&2
-    exit 1
-fi
-echo "Current latest release: $latest_release"
-
-# Ask for new version
-read -p "Enter new version (e.g., 1.0.4): " new_version
-
-# Validate version format
-if ! [[ $new_version =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
-    echo "Error: Version must be in format X.Y.Z (e.g., 1.0.4)" >&2
-    exit 1
-fi
-
-# Get script directory
-script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-
-# Change to script directory
-cd "$script_dir" || { echo "Error: Could not change to script directory" >&2; exit 1; }
-
-# hero_v_path="$script_dir/cli/hero.v"
-
-# # Read hero.v and check if it exists
-# if [ ! -f "$hero_v_path" ]; then
-#     echo "Error: $hero_v_path does not exist" >&2
-#     exit 1
-# fi
-
-# # Create backup of hero.v
-# cp "$hero_v_path" "$hero_v_path.backup" || {
-#     echo "Error creating backup of $hero_v_path" >&2
-#     exit 1
-# }
-
-# # Update version in hero.v
-# if ! sed -i.bak "s/\(.*version:[ ]*\)'[^']*'/\1'$new_version'/" "$hero_v_path"; then
-#     echo "Error updating version in $hero_v_path" >&2
-#     # Restore backup
-#     cp "$hero_v_path.backup" "$hero_v_path" || echo "Error restoring backup" >&2
-#     exit 1
-# fi
-
-# # Clean up backup
-# rm -f "$hero_v_path.backup" "$hero_v_path.bak" || echo "Warning: Could not remove backup file" >&2
-
-# # Update version in install_hero.sh
-# install_hero_path="$script_dir/install_hero.sh"
-
-# # Check if install_hero.sh exists
-# if [ ! -f "$install_hero_path" ]; then
-#     echo "Error: $install_hero_path does not exist" >&2
-#     exit 1
-# fi
-
-# # Create backup of install_hero.sh
-# cp "$install_hero_path" "$install_hero_path.backup" || {
-#     echo "Error creating backup of $install_hero_path" >&2
-#     exit 1
-# }
-
-# # Update version in install_hero.sh
-# if ! sed -i.bak "s/version='[^']*'/version='$new_version'/" "$install_hero_path"; then
-#     echo "Error updating version in $install_hero_path" >&2
-#     # Restore backup
-#     cp "$install_hero_path.backup" "$install_hero_path" || echo "Error restoring backup" >&2
-#     exit 1
-# fi
-
-# # Clean up backup
-# rm -f "$install_hero_path.backup" "$install_hero_path.bak" || echo "Warning: Could not remove backup file" >&2
-
-# Prepare git commands
-cmd="
-git remote set-url origin git@github.com:incubaid/herolib.git
-git add $hero_v_path $install_hero_path
-git commit -m \"bump version to $new_version\"
-git pull git@github.com:incubaid/herolib.git main
-git tag -a \"v$new_version\" -m \"Release version $new_version\"
-git push git@github.com:incubaid/herolib.git \"v$new_version\"
-"
-
-echo "$cmd"
-
-# Execute git commands
-eval "$cmd"
-
-echo "Release v$new_version created and pushed!"