FlexLove/docs/README.md

FlexLöve Documentation

This directory contains auto-generated API documentation from LuaLS annotations.

Files

• api.html - Beautiful, searchable API documentation (2.2MB)
• index.html - GitHub Pages landing page
• build-docs.js - Node.js script to convert markdown to HTML
• package.json - Node.js dependencies for HTML generation
• .nojekyll - Tells GitHub Pages to bypass Jekyll processing
• doc.md - Raw markdown (gitignored, 960KB)
• doc.json - Raw JSON (gitignored, 11MB)

Regenerating Documentation

To regenerate the documentation after making changes:

./scripts/generate_docs.sh

This will:

1. Extract version from FlexLove.lua (single source of truth)
2. Generate markdown from LuaLS annotations
3. Convert to beautiful, searchable HTML with syntax highlighting
4. Create navigation sidebar with search functionality
5. Display version in page titles and headers

Viewing Locally

Open index.html in your browser:

open docs/index.html  # macOS
xdg-open docs/index.html  # Linux
start docs/index.html  # Windows

Publishing to GitHub Pages

1. Commit the docs/ directory:

   git add docs/
   git commit -m "Update documentation"
   git push
   

2. Enable GitHub Pages in repository settings:

   • Go to Settings > Pages
   • Source: Deploy from a branch
   • Branch: main (or your default branch)
   • Folder: /docs
   • Save

3. Your documentation will be available at: https://[username].github.io/[repository]/

Documentation Format

The documentation is generated from LuaLS (Lua Language Server) annotations using the lua-language-server CLI tool. This ensures 100% compatibility with your IDE autocomplete and type checking.

Supported Annotations

• ---@class - Class definitions
• ---@field - Class fields
• ---@param - Function parameters
• ---@return - Return values
• ---@type - Variable types
• And all other LuaLS annotations

Requirements

• lua-language-server - For generating markdown from annotations

  • macOS: brew install lua-language-server
  • Linux: See https://github.com/LuaLS/lua-language-server

• Node.js - For converting markdown to beautiful HTML

  • macOS: brew install node
  • Linux: Use your package manager or https://nodejs.org

Features

The generated HTML documentation includes:

• 🔍 Live search - Find classes and methods instantly
• 📱 Responsive design - Works on all devices
• 🌙 Dark theme - Easy on the eyes
• 🎨 Syntax highlighting - Code examples are beautifully formatted
• 🗂️ Collapsible navigation - Organized class/method structure
• ⚡ Fast - Single-page application, no page reloads
• 🎯 Filtered - Only user-facing classes, no internal implementation
• 🏷️ Versioned - Auto-displays version from FlexLove.lua

Customizing Documentation

Edit doc-filter.js to control which classes appear in the documentation:

module.exports = {
  // Whitelist mode: Only these classes will be included
  include: [
    'Animation',
    'Color',
    'Element',
    'Theme',
    // ... add more
  ],
  
  // Blacklist mode: These classes will be excluded
  exclude: [
    'Context',
    'Performance',
    // ... add more
  ],
  
  // Which mode to use
  mode: 'whitelist'  // or 'blacklist'
};

Current filter: Whitelist mode with 20 classes (down from 33)

Version Management

The documentation automatically pulls the version from FlexLove.lua:

flexlove._VERSION = "0.2.0"  -- Single source of truth

To update the version:

1. Change _VERSION in FlexLove.lua
2. Run ./scripts/generate_docs.sh
3. Version appears in page titles, sidebar, and footer

See VERSIONING.md for detailed version management workflow.