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.
|
||||
|
||||
## 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.
|
||||
|
||||
Reference in New Issue
Block a user