137 lines
3.7 KiB
Markdown
137 lines
3.7 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
./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:
|
|
|
|
```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.
|