simplified

This commit is contained in:
Michael Freno
2025-11-16 09:40:43 -05:00
parent 9c6c8a061b
commit f4d514bf2e

View File

@@ -2,16 +2,6 @@
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:
@@ -23,114 +13,6 @@ To regenerate the documentation after making changes:
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
3. Convert to 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:
```bash
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:
```bash
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:
```javascript
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`:
```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.