100 lines
3.3 KiB
Plaintext
100 lines
3.3 KiB
Plaintext
# ╔══════════════════════════════════════════════════════════════════════╗
|
|
# ║ DOCUMENTATION TOOLS ║
|
|
# ║ mdBook build, serve, and management ║
|
|
# ╚══════════════════════════════════════════════════════════════════════╝
|
|
|
|
# === PATHS ===
|
|
DOCS_DIR := "docs"
|
|
BOOK_DIR := "book"
|
|
|
|
# Help for docs module
|
|
help:
|
|
@echo "DOCUMENTATION MODULE"
|
|
@echo ""
|
|
@echo "Build and serve:"
|
|
@echo " just docs::build Build mdBook"
|
|
@echo " just docs::serve Serve mdBook locally"
|
|
@echo " just docs::watch Watch and rebuild on changes"
|
|
@echo ""
|
|
@echo "Validation:"
|
|
@echo " just docs::test Test documentation examples"
|
|
@echo " just docs::check-links Check for broken links"
|
|
@echo ""
|
|
@echo "Cleanup:"
|
|
@echo " just docs::clean Clean build artifacts"
|
|
|
|
# === BUILD AND SERVE ===
|
|
|
|
# Build mdBook documentation
|
|
[doc("Build mdBook documentation")]
|
|
build:
|
|
@echo "=== Building mdBook ==="
|
|
@if command -v mdbook >/dev/null 2>&1; then \
|
|
cd {{ DOCS_DIR }} && mdbook build; \
|
|
echo "✓ mdBook built successfully"; \
|
|
else \
|
|
echo "Error: mdbook not installed"; \
|
|
echo "Install with: cargo install mdbook"; \
|
|
exit 1; \
|
|
fi
|
|
|
|
# Serve mdBook locally
|
|
[doc("Serve mdBook locally (http://localhost:3000)")]
|
|
serve:
|
|
@echo "=== Serving mdBook ==="
|
|
@if command -v mdbook >/dev/null 2>&1; then \
|
|
echo "Opening http://localhost:3000"; \
|
|
cd {{ DOCS_DIR }} && mdbook serve --open; \
|
|
else \
|
|
echo "Error: mdbook not installed"; \
|
|
echo "Install with: cargo install mdbook"; \
|
|
exit 1; \
|
|
fi
|
|
|
|
# Watch and rebuild on changes
|
|
[doc("Watch docs and rebuild on changes")]
|
|
watch:
|
|
@echo "=== Watching documentation ==="
|
|
@if command -v mdbook >/dev/null 2>&1; then \
|
|
cd {{ DOCS_DIR }} && mdbook watch; \
|
|
else \
|
|
echo "Error: mdbook not installed"; \
|
|
echo "Install with: cargo install mdbook"; \
|
|
exit 1; \
|
|
fi
|
|
|
|
# === VALIDATION ===
|
|
|
|
# Test documentation code examples
|
|
[doc("Test documentation code examples")]
|
|
test:
|
|
@echo "=== Testing documentation examples ==="
|
|
@if command -v mdbook >/dev/null 2>&1; then \
|
|
cd {{ DOCS_DIR }} && mdbook test; \
|
|
echo "✓ Documentation tests passed"; \
|
|
else \
|
|
echo "Error: mdbook not installed"; \
|
|
exit 1; \
|
|
fi
|
|
|
|
# Check for broken links
|
|
[doc("Check for broken links in documentation")]
|
|
check-links:
|
|
@echo "=== Checking for broken links ==="
|
|
@if command -v mdbook-linkcheck >/dev/null 2>&1; then \
|
|
cd {{ DOCS_DIR }} && mdbook-linkcheck; \
|
|
echo "✓ No broken links found"; \
|
|
else \
|
|
echo "Warning: mdbook-linkcheck not installed"; \
|
|
echo "Install with: cargo install mdbook-linkcheck"; \
|
|
fi
|
|
|
|
# === CLEANUP ===
|
|
|
|
# Clean build artifacts
|
|
[doc("Clean mdBook build artifacts")]
|
|
clean:
|
|
@echo "=== Cleaning mdBook artifacts ==="
|
|
@rm -rf {{ DOCS_DIR }}/{{ BOOK_DIR }}
|
|
@echo "✓ Cleaned build artifacts"
|