simplified
This commit is contained in:
120
docs/README.md
120
docs/README.md
@@ -2,16 +2,6 @@
|
|||||||
|
|
||||||
This directory contains auto-generated API documentation from LuaLS annotations.
|
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
|
## Regenerating Documentation
|
||||||
|
|
||||||
To regenerate the documentation after making changes:
|
To regenerate the documentation after making changes:
|
||||||
@@ -23,114 +13,6 @@ To regenerate the documentation after making changes:
|
|||||||
This will:
|
This will:
|
||||||
1. Extract version from `FlexLove.lua` (single source of truth)
|
1. Extract version from `FlexLove.lua` (single source of truth)
|
||||||
2. Generate markdown from LuaLS annotations
|
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
|
4. Create navigation sidebar with search functionality
|
||||||
5. Display version in page titles and headers
|
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.
|
|
||||||
|
|||||||
Reference in New Issue
Block a user