1 line
6.0 KiB
Markdown
1 line
6.0 KiB
Markdown
# Provisioning Platform Documentation\n\nComplete documentation for the Provisioning Platform infrastructure automation system built with Nushell,\nNickel, and Rust.\n\n## 📖 Browse Documentation\n\nAll documentation is **directly readable** as markdown files in Git/GitHub—mdBook is optional.\n\n- **[Table of Contents](src/SUMMARY.md)** – Complete documentation index (188+ pages)\n- **[Browse src/ directory](src/)** – All markdown files organized by topic\n\n---\n\n## 🚀 Quick Navigation\n\n### For Users & Operators\n\n- **[Getting Started](src/getting-started/)** – Installation, setup, and first deployment\n- **[Operations Guide](src/operations/)** – Deployment, monitoring, orchestrator management\n- **[Troubleshooting](src/troubleshooting/troubleshooting-guide.md)** – Common issues and solutions\n- **[Security](src/security/)** – Authentication, encryption, secrets management\n\n### For Developers & Architects\n\n- **[Architecture Overview](src/architecture/)** – System design and integration patterns\n- **[Infrastructure Guide](src/infrastructure/)** – CLI, configuration system, workspaces\n- **[Development Guide](src/development/)** – Extensions, providers, taskservs, build system\n- **[API Reference](src/api-reference/)** – REST API, WebSocket, SDKs, integration examples\n\n### For Advanced Users\n\n- **[Deployment Guides](src/guides/)** – Multi-provider setup, customization, infrastructure examples\n- **[Integration Guides](src/integration/)** – Gitea, OCI, service mesh, secrets integration\n- **[Testing](src/testing/)** – Test environment setup and validation\n\n---\n\n## 📚 Documentation Structure\n\n```{$detected_lang}\nprovisioning/docs/\n├── README.md # This file – navigation hub\n├── book.toml # mdBook configuration\n├── src/ # Source markdown files (version-controlled)\n│ ├── SUMMARY.md # Complete table of contents\n│ ├── getting-started/ # Installation and setup\n│ ├── architecture/ # System design and ADRs\n│ ├── infrastructure/ # CLI, configuration, workspaces\n│ ├── operations/ # Deployment, orchestrator, monitoring\n│ ├── development/ # Extensions, providers, build system\n│ ├── api-reference/ # APIs and SDKs\n│ ├── security/ # Authentication, secrets, encryption\n│ ├── integration/ # Third-party integrations\n│ ├── guides/ # How-to guides and examples\n│ ├── troubleshooting/ # Common issues\n│ └── ... # 12 other sections\n├── book/ # Generated HTML output (Git-ignored)\n└── examples/ # Example workspace configurations\n```\n\n### Why `src/` subdirectory\n\nThis is the **standard mdBook convention**:\n- **Source (`src/`)**: Version-controlled markdown files, directly readable\n- **Output (`book/`)**: Generated HTML/CSS/JS, Git-ignored (regenerated on build)\n\nThis separation allows the same source files to generate multiple output formats (HTML, PDF, EPUB) without\ncluttering the version-controlled repository.\n\n---\n\n## 🔨 Building HTML with mdBook\n\nIf you prefer a formatted HTML website with search, themes, and copy buttons, build with mdBook:\n\n### Prerequisites\n\n```bash\ncargo install mdbook\n```\n\n### Build & Serve\n\n```bash\n# Navigate to docs directory\ncd provisioning/docs\n\n# Build HTML to book/ directory\nmdbook build\n\n# Serve locally at http://localhost:3000 (with live reload)\nmdbook serve\n```\n\n### Output\n\nGenerated HTML is available in `provisioning/docs/book/` after building.\n\n**Note**: mdBook is entirely optional. The markdown files in `src/` work perfectly fine in any Git\nviewer or text editor.\n\n---\n\n## 📖 Reading Markdown Directly\n\nAll documentation is standard GitHub Flavored Markdown. You can:\n\n- **GitHub/GitLab**: Click `provisioning/docs/src/` and browse directly\n- **Local Git**: Clone the repo and open any `.md` file in your editor\n- **Text Search**: Use `grep` or your editor's search to find topics across all markdown files\n- **mdBook (optional)**: Build HTML for formatted reading with search and theming\n\n---\n\n## 🔗 Key Reference Pages\n\n| Document | Purpose |\n| ------------------------------------------------------------------------------ | --------------------------------- |\n| [System Overview](src/architecture/system-overview.md) | High-level architecture |\n| [Installation Guide](src/getting-started/installation-guide.md) | Step-by-step setup |\n| [CLI Reference](src/infrastructure/cli-reference.md) | Command reference |\n| [Configuration System](src/infrastructure/configuration-system.md) | Config management |\n| [Security System](src/security/security-system.md) | Authentication & encryption |\n| [Orchestrator](src/operations/orchestrator.md) | Service orchestration |\n| [Workspace Guide](src/infrastructure/workspaces/workspace-guide.md) | Infrastructure workspaces |\n| [ADRs](src/architecture/adr/) | Architecture Decision Records |\n\n---\n\n## ❓ Questions\n\n- **Getting started** → Start with [Installation Guide](src/getting-started/installation-guide.md)\n- **Having issues** → Check [Troubleshooting](src/troubleshooting/troubleshooting-guide.md)\n- **Looking for API docs** → See [API Reference](src/api-reference/)\n- **Want architecture details** → Read [Architecture Overview](src/architecture/architecture-overview.md)\n\nFor complete navigation, see [Table of Contents](src/SUMMARY.md). |