9cef9b8d57
Merge _configs/ into config/ for single configuration directory. Update all path references. Changes: - Move _configs/* to config/ - Update .gitignore for new patterns - No code references to _configs/ found Impact: -1 root directory (layout_conventions.md compliance)
294 lines
7.3 KiB
Markdown
294 lines
7.3 KiB
Markdown
# SYNTAXIS Bundle Documentation Guide
|
|
|
|
**Quick reference for managing bundle documentation.**
|
|
|
|
---
|
|
|
|
## 📍 Where Documents Live
|
|
|
|
All bundle documentation is in `docs/`:
|
|
|
|
```bash
|
|
docs/
|
|
├── BUNDLE_README.md ← Bundle overview (becomes README.md in bundle)
|
|
├── docs/installation.md ← Installation guide
|
|
├── QUICK_START.md ← 5-minute getting started
|
|
├── CONFIG.md ← Configuration reference
|
|
├── TROUBLESHOOTING.md ← Common issues & solutions
|
|
├── PACK.md ← Provisioning system docs
|
|
├── BUNDLE_DOCS_REFERENCE.md ← (This document - detailed reference)
|
|
│
|
|
├── (Development docs - NOT in bundle)
|
|
├── ARCHITECTURE.md
|
|
├── CLI_QUICK_REFERENCE.md
|
|
├── SURREALDB_*.md
|
|
└── PERSISTENCE_*.md
|
|
```
|
|
|
|
---
|
|
|
|
## 🔄 Update & Rebuild Cycle
|
|
|
|
```
|
|
1. Edit docs/ → 2. Run pack.nu → 3. Distribute bundle
|
|
|
|
Edit: Build: Users get:
|
|
docs/docs/installation.md nu scripts/ syntaxis-v0.1.0-*.tar.gz
|
|
docs/CONFIG.md provisioning/ (includes latest docs)
|
|
docs/QUICK_START.md pack.nu
|
|
(any source files)
|
|
```
|
|
|
|
---
|
|
|
|
## ✏️ How to Update for Next Pack
|
|
|
|
### Quick Steps
|
|
|
|
```bash
|
|
# 1. Edit a document
|
|
nano docs/docs/installation.md
|
|
|
|
# 2. Build new bundle
|
|
nu scripts/provisioning/pack.nu
|
|
|
|
# 3. That's it! Bundle in dist/ has latest docs
|
|
```
|
|
|
|
### Detailed: Where Each Doc Goes
|
|
|
|
| Source File | Bundle Location | Purpose |
|
|
|---|---|---|
|
|
| `docs/BUNDLE_README.md` | `README.md` (root) | First thing users see |
|
|
| `docs/docs/installation.md` | `docs/installation.md` (root) | High visibility |
|
|
| `docs/QUICK_START.md` | `QUICK_START.md` (root) | First 5 minutes |
|
|
| `docs/CONFIG.md` | `docs/CONFIG.md` | Configuration reference |
|
|
| `docs/TROUBLESHOOTING.md` | `docs/TROUBLESHOOTING.md` | Problem solving |
|
|
| `docs/PACK.md` | `docs/PACK.md` | Provisioning info |
|
|
|
|
---
|
|
|
|
## 📋 What to Update When
|
|
|
|
| If... | Edit This | Reason |
|
|
|---|---|---|
|
|
| Users report installation issues | `docs/TROUBLESHOOTING.md` | Help future users |
|
|
| Configuration options change | `docs/CONFIG.md` | Keep docs accurate |
|
|
| Installation workflow changes | `docs/docs/installation.md` | Users follow new steps |
|
|
| Getting started changes | `docs/QUICK_START.md` | First impression matters |
|
|
| Bundle contents change | `docs/BUNDLE_README.md` | Describe what's inside |
|
|
| Provisioning system changes | `docs/PACK.md` | Document the system |
|
|
|
|
---
|
|
|
|
## 🔗 Configuration: provisioning.toml
|
|
|
|
Located: `configs/provisioning.toml`
|
|
|
|
Currently references (automatically used by pack.nu):
|
|
|
|
```toml
|
|
[artifacts]
|
|
docs = [
|
|
"docs/BUNDLE_README.md",
|
|
"docs/docs/installation.md",
|
|
"docs/QUICK_START.md",
|
|
"docs/CONFIG.md",
|
|
"docs/TROUBLESHOOTING.md",
|
|
"docs/PACK.md",
|
|
]
|
|
|
|
scripts = [
|
|
"scripts/provisioning/provision.sh",
|
|
"scripts/provisioning/install.sh",
|
|
"scripts/provisioning/install.nu",
|
|
"scripts/provisioning/setup-config.sh",
|
|
]
|
|
```
|
|
|
|
**To add a new doc:** Add line to `docs = [...]` array, save, run pack.nu.
|
|
|
|
---
|
|
|
|
## 📦 Automatic Reuse
|
|
|
|
Each time you run `pack.nu`:
|
|
|
|
✅ Reads latest `provisioning.toml`
|
|
✅ Finds all referenced doc files
|
|
✅ Copies latest versions
|
|
✅ Renames/places them correctly
|
|
✅ Generates SHA256 checksums
|
|
✅ Creates bundle archive
|
|
|
|
**No duplication needed.** Edit once, use forever.
|
|
|
|
---
|
|
|
|
## 🛠️ Build Commands
|
|
|
|
```bash
|
|
# Build for current system
|
|
nu scripts/provisioning/pack.nu
|
|
|
|
# Build for specific platform
|
|
nu scripts/provisioning/pack.nu --target x86_64-unknown-linux-gnu
|
|
|
|
# Different format (zip instead of tar.gz)
|
|
nu scripts/provisioning/pack.nu --format zip
|
|
|
|
# Verify bundle integrity
|
|
nu scripts/provisioning/pack.nu --verify
|
|
|
|
# Preview what would be packaged
|
|
nu scripts/provisioning/pack.nu --dry-run
|
|
```
|
|
|
|
---
|
|
|
|
## 📂 File Structure After Pack
|
|
|
|
Bundle created in: `dist/`
|
|
|
|
```
|
|
dist/
|
|
├── syntaxis-v0.1.0-aarch64-apple-darwin.tar.gz ← User distributes this
|
|
├── syntaxis-v0.1.0-aarch64-apple-darwin.checksums.toml ← Optional checksum file
|
|
```
|
|
|
|
When user extracts:
|
|
|
|
```
|
|
syntaxis-v0.1.0-aarch64-apple-darwin/
|
|
├── README.md # From docs/BUNDLE_README.md
|
|
├── docs/installation.md # From docs/docs/installation.md
|
|
├── QUICK_START.md # From docs/QUICK_START.md
|
|
├── provision.sh # Master provisioner (recommended)
|
|
├── install.sh # Bash installer (optional)
|
|
├── setup-config.sh # Config helper
|
|
└── docs/
|
|
├── CONFIG.md # From docs/CONFIG.md
|
|
├── TROUBLESHOOTING.md # From docs/TROUBLESHOOTING.md
|
|
└── PACK.md # From docs/PACK.md
|
|
```
|
|
|
|
---
|
|
|
|
## 💡 Pro Tips
|
|
|
|
### Tip 1: Check What's In Your Bundle
|
|
|
|
```bash
|
|
# List all files in latest bundle
|
|
tar -tzf dist/syntaxis-v0.1.0-*.tar.gz | head -30
|
|
|
|
# Extract and view specific doc
|
|
tar -xzOf dist/syntaxis-v0.1.0-*.tar.gz \
|
|
'syntaxis-v0.1.0-*/docs/installation.md' | head -20
|
|
```
|
|
|
|
### Tip 2: Verify Changes Made It In
|
|
|
|
```bash
|
|
# Before and after comparison
|
|
tar -tzf dist/syntaxis-v0.1.0-*.tar.gz | grep README.md
|
|
```
|
|
|
|
### Tip 3: Update Multiple Docs at Once
|
|
|
|
```bash
|
|
# Edit all bundle docs
|
|
nano docs/BUNDLE_README.md
|
|
nano docs/docs/installation.md
|
|
nano docs/QUICK_START.md
|
|
nano docs/CONFIG.md
|
|
|
|
# One pack command includes all changes
|
|
nu scripts/provisioning/pack.nu
|
|
```
|
|
|
|
### Tip 4: Version Control
|
|
|
|
```bash
|
|
# Track doc changes with git
|
|
git add docs/docs/installation.md
|
|
git commit -m "docs: update installation steps for new provision script"
|
|
|
|
# Pack the new version
|
|
nu scripts/provisioning/pack.nu
|
|
|
|
# Users get latest with next bundle distribution
|
|
```
|
|
|
|
---
|
|
|
|
## 🧹 Cleanup
|
|
|
|
Old files removed (superseded by new ones):
|
|
|
|
- ~~`docs/CONFIG_GUIDE.md`~~ → replaced by `docs/CONFIG.md`
|
|
- ~~`docs/BUNDLE_docs/installation.md`~~ → replaced by `docs/docs/installation.md`
|
|
|
|
**Development-only docs (NOT in bundle):**
|
|
- `docs/ARCHITECTURE.md` - For developers
|
|
- `docs/CLI_QUICK_REFERENCE.md` - For developers
|
|
- `docs/SURREALDB_*.md` - Advanced/developer
|
|
- `docs/PERSISTENCE_*.md` - Advanced/developer
|
|
|
|
---
|
|
|
|
## 🚀 Example: Adding a New Guide
|
|
|
|
**Scenario:** You want to add a "First Deployment" guide to bundles
|
|
|
|
```bash
|
|
# 1. Create the new guide
|
|
cat > docs/FIRST_DEPLOYMENT.md << 'EOF'
|
|
# First Deployment Guide
|
|
...content here...
|
|
EOF
|
|
|
|
# 2. Add it to provisioning.toml
|
|
# Edit: configs/provisioning.toml
|
|
# In [artifacts] docs array, add:
|
|
# "docs/FIRST_DEPLOYMENT.md",
|
|
|
|
# 3. Rebuild bundle
|
|
nu scripts/provisioning/pack.nu
|
|
|
|
# 4. New bundle includes it automatically
|
|
```
|
|
|
|
---
|
|
|
|
## 📞 Quick Reference Card
|
|
|
|
```
|
|
LOCATION: docs/
|
|
CONFIG: configs/provisioning.toml [artifacts] docs = [...]
|
|
BUILD: nu scripts/provisioning/pack.nu
|
|
OUTPUT: dist/syntaxis-v0.1.0-*.tar.gz
|
|
EDIT: nano docs/<filename>.md
|
|
THEN: nu scripts/provisioning/pack.nu
|
|
DONE: Bundle ready for distribution with latest docs
|
|
```
|
|
|
|
---
|
|
|
|
## 📖 Related Documentation
|
|
|
|
For more detailed information, see:
|
|
|
|
- **`docs/BUNDLE_DOCS_REFERENCE.md`** - Comprehensive reference
|
|
- **`docs/PACK.md`** - Provisioning system details
|
|
- **`docs/docs/installation.md`** - Installation guide
|
|
- **`configs/provisioning.toml`** - Bundle configuration
|
|
|
|
---
|
|
|
|
**SYNTAXIS** v0.1.0
|
|
|
|
Bundle Documentation is user-focused, source-controlled, and automatically included in every pack.
|
|
|
|
Simple workflow: Edit → Pack → Distribute → Users get latest docs.
|