154 lines
4.1 KiB
Markdown
154 lines
4.1 KiB
Markdown
# Documentation Workflow
|
|
|
|
## Overview
|
|
|
|
FlexLöve's documentation system automatically manages versioning and archival. When you generate new documentation, the previous version is automatically archived.
|
|
|
|
## How It Works
|
|
|
|
### 1. Manual Documentation Updates (No Version Change)
|
|
|
|
When you update annotations without bumping the version:
|
|
|
|
```bash
|
|
./scripts/generate_docs.sh
|
|
```
|
|
|
|
**What happens:**
|
|
- Script detects current version (e.g., v0.2.0) from `docs/api.html`
|
|
- Compares with `FlexLove.lua` version
|
|
- If versions match: **Overwrites** `docs/api.html` (same version)
|
|
- Previous archived version remains unchanged
|
|
|
|
**Use case:** You added better documentation, fixed typos, or improved examples without releasing a new version.
|
|
|
|
### 2. Version Bump (New Release)
|
|
|
|
When you bump the version in `FlexLove.lua`:
|
|
|
|
```bash
|
|
# 1. Update version in FlexLove.lua
|
|
# flexlove._VERSION = "0.3.0"
|
|
|
|
# 2. Generate documentation
|
|
./scripts/generate_docs.sh
|
|
```
|
|
|
|
**What happens:**
|
|
- Script detects old version (v0.2.0) from `docs/api.html`
|
|
- Compares with new version (v0.3.0) from `FlexLove.lua`
|
|
- **Archives** old `docs/api.html` → `docs/versions/v0.2.0/api.html`
|
|
- Generates new `docs/api.html` for v0.3.0
|
|
|
|
### 3. Automated Release (via GitHub Actions)
|
|
|
|
When you push a git tag:
|
|
|
|
```bash
|
|
git tag v0.3.0
|
|
git push origin v0.3.0
|
|
```
|
|
|
|
**What happens:**
|
|
1. GitHub Actions workflow triggers
|
|
2. Archives previous documentation version
|
|
3. Generates new documentation for v0.3.0
|
|
4. Commits both archived and new docs to repository
|
|
5. Creates release package with checksums
|
|
6. Creates GitHub release with assets
|
|
|
|
## Directory Structure
|
|
|
|
```
|
|
docs/
|
|
├── api.html # Always the LATEST version
|
|
├── index.html # Landing page
|
|
└── versions/
|
|
├── v0.1.0/
|
|
│ └── api.html # Documentation for v0.1.0
|
|
├── v0.2.0/
|
|
│ └── api.html # Documentation for v0.2.0
|
|
└── v0.3.0/
|
|
└── api.html # Documentation for v0.3.0
|
|
```
|
|
|
|
## Version Detection
|
|
|
|
The system automatically detects versions by:
|
|
1. **Current docs version**: Reads from `docs/api.html` header (`FlexLöve v0.2.0`)
|
|
2. **Code version**: Reads from `FlexLove.lua` (`flexlove._VERSION = "0.2.0"`)
|
|
|
|
### Behavior Matrix
|
|
|
|
| Old Version | New Version | Action |
|
|
|-------------|-------------|--------|
|
|
| v0.2.0 | v0.2.0 | Overwrite current (same version update) |
|
|
| v0.2.0 | v0.3.0 | Archive v0.2.0, generate v0.3.0 |
|
|
| None | v0.2.0 | Generate v0.2.0 (first time) |
|
|
|
|
## Examples
|
|
|
|
### Scenario 1: Fix Documentation Typo
|
|
|
|
```bash
|
|
# Fix typo in annotations
|
|
# Version still 0.2.0 in FlexLove.lua
|
|
|
|
./scripts/generate_docs.sh
|
|
# Output: "Same version (v0.2.0), will overwrite current documentation"
|
|
# Result: docs/api.html updated, no archival
|
|
```
|
|
|
|
### Scenario 2: Release New Version
|
|
|
|
```bash
|
|
# Update FlexLove.lua
|
|
# flexlove._VERSION = "0.3.0"
|
|
|
|
./scripts/generate_docs.sh
|
|
# Output: "Found previous version v0.2.0, archiving before generating new docs..."
|
|
# Output: "✓ Archived previous documentation to docs/versions/v0.2.0/"
|
|
# Result:
|
|
# - docs/versions/v0.2.0/api.html (archived)
|
|
# - docs/api.html (new v0.3.0)
|
|
```
|
|
|
|
### Scenario 3: Automated Release
|
|
|
|
```bash
|
|
# Tag and push
|
|
git tag v0.3.0
|
|
git push origin v0.3.0
|
|
|
|
# GitHub Actions will:
|
|
# 1. Archive v0.2.0 automatically
|
|
# 2. Generate v0.3.0 docs
|
|
# 3. Commit both to repository
|
|
# 4. Create GitHub release
|
|
```
|
|
|
|
## Benefits
|
|
|
|
✅ **No manual archival needed** - Automatically handled
|
|
✅ **Safe overwrites** - Same version updates won't create duplicate archives
|
|
✅ **Version history preserved** - All previous versions accessible
|
|
✅ **Seamless workflow** - Just run `./scripts/generate_docs.sh`
|
|
✅ **Automated releases** - Tag and forget
|
|
|
|
## Version Dropdown
|
|
|
|
Users can access any version via the dropdown in the documentation header:
|
|
- Current version shows "(Latest)" badge
|
|
- Previous versions listed chronologically
|
|
- Click to navigate to archived documentation
|
|
|
|
## Manual Archival (If Needed)
|
|
|
|
If you ever need to manually archive a version:
|
|
|
|
```bash
|
|
./scripts/archive-docs.sh
|
|
```
|
|
|
|
This creates `docs/versions/v{version}/api.html` based on the current `FlexLove.lua` version.
|