refactor: Merge documentation repo with playbook (#10)

Author: g3force

.github/workflows/build-antora.yml

@@ -1,62 +1,34 @@
 # Reusable Workflow: Build Antora Documentation Site
 # This workflow can be called from other workflows to build the Antora site.
-# Includes Kroki/Mermaid services for diagram rendering.
 
 name: Build Antora Site
 
 on:
-  workflow_call:
-    inputs:
-      node-version:
-        description: 'Node.js version to use'
-        required: false
-        type: string
-        default: '24.3.0'
-      playbook-file:
-        description: 'Path to Antora playbook file'
-        required: false
-        type: string
-        default: 'antora-playbook.yml'
-    outputs:
-      build-path:
-        description: 'Path to the built site directory'
-        value: 'build/site'
+  workflow_call: {}
 
 jobs:
   build:
     runs-on: ubuntu-latest
 
-    services:
-      mermaid:
-        image: yuzutech/kroki-mermaid:latest
-        ports:
-          - 8002:8002
-      kroki:
-        image: yuzutech/kroki:latest
-        env:
-          KROKI_MERMAID_HOST: mermaid
-        ports:
-          - 8000:8000
-        options: >-
-          --health-cmd "curl -f http://localhost:8000/health || exit 1"
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 5
-
     steps:
       - name: Checkout playbook source
         uses: actions/checkout@v6
 
       - name: Setup Node.js
         uses: actions/setup-node@v6
         with:
-          node-version: ${{ inputs.node-version }}
+          node-version: 24
 
       - name: Install Antora and Dependencies
         run: npm install
 
+      - name: Run docker compose
+        uses: hoverkraft-tech/compose-action@05da55b2bb8a5a759d1c4732095044bd9018c050 # v2.4.3
+        with:
+          compose-file: './compose.yml'
+
       - name: Generate Site
-        run: npx antora generate --log-failure-level warn ${{ inputs.playbook-file }}
+        run: npm run build
 
       - name: Upload built site
         uses: actions/upload-artifact@v6

.github/workflows/deploy-docs.yml .github/workflows/publish.yml.github/workflows/deploy-docs.yml renamed to .github/workflows/publish.yml

@@ -1,4 +1,4 @@
-/build/
-.cache/
-.idea/
-/node_modules/
+.idea
+build
+node_modules
+.cache

.gitignore

@@ -1,34 +1,25 @@
-# Antora Playbook
+# Agentic Layer Documentation
 
-A documentation site generator configuration that aggregates and publishes documentation from multiple Git repositories into a unified, searchable documentation website for the Agentic Layer ecosystem.
-
-----
-
-## Table of Contents
-
-- [Getting Started](#getting-started)
-- [Configuration](#configuration)
-- [Publishing](#publishing)
-- [Contributing](#contributing)
-
-----
+Documentation of the Agentic Layer ecosystem, built with Antora by aggregating content from multiple Git repositories.
 
 ## Getting Started
 
-### Installation
-
 Install all required dependencies:
 
-```bash
+```shell
 npm install
 ```
 
-### Starting the Documentation Build
+Start kroki backend for diagram generation:
+
+```shell
+docker compose up -d
+```
 
 Generate the documentation site:
 
-```bash
-npx antora antora-playbook.yml
+```shell
+npm run build
 ```
 
 After successful completion, the generated documentation site will be available in the `build/site` directory.
@@ -37,86 +28,4 @@ Troubleshooting tips:
 - Ensure all referenced Git repositories and branches are accessible.
 - Clear the cache if you encounter issues: `rm -rf .cache/antora`
 
-## Configuration
-
-The project is configured through the `antora-playbook.yml` file, which defines:
-
-### Site Configuration
-- **Title**: Agentic Layer Documentation
-- **URL**: https://docs.agentic-layer.ai
-- **Start Page**: home::index.adoc
-
-### Content Sources
-Source repositories are defined in `content.sources` array of `antora-playbook.yml`.
-
-### UI Configuration
-- Uses the default Antora UI theme from GitLab
-- Custom UI overrides are stored in `supplemental-ui/` directory
-- Navigation includes links to source Git repositories
-
-### Output Configuration
-- Generated site output: `build/site/`
-- Cache directory: `.cache/antora/` (for performance optimization)
-
-## Publishing
-The playbook is set up for GitHub Pages deployment defined in `./.github/workflows/deploy-docs.yml`.
-
-## Contributing
-
-### Adding New GitHub Repositories
-
-To add a new GitHub repository as a documentation source to the antora-playbook:
-
-1. **Repository Requirements**
-   - Set up the following documentation structure in your new source repository `root`: 
-      ```
-      docs
-      ├── antora.yml
-      └── modules
-          └── ROOT
-              ├── nav.adoc
-              ├── pages
-              │   └── index.adoc
-              └── partials
-                  ├── explanation.adoc
-                  ├── how-to-guides.adoc
-                  ├── reference.adoc
-                  └── tutorials.adoc
-      
-      ```   
-
-   - `antora.yml` describes the component. Example:
-     ```yaml
-      name: <COMPONENT_NAME>
-      title: <COMPONENT_TITLE>
-      version: main # or your versioning scheme
-      start_page: ROOT:index.adoc
-      nav:
-      - modules/ROOT/nav.adoc
-     ```
-
-2. **Update antora-playbook.yml**
-   - Add a new entry to the `content.sources` array
-   - Specify the GitHub repository URL
-   - Define which branches to include (use `['feature/*']` for development, `[main]` for production)
-   - Set the `start_path` if documentation is not in the root (typically `docs`)
-
-   Example:
-   ```yaml
-   - url: https://github.com/agentic-layer/your-new-repo.git
-     branches: ['feature/*']  # Change to [main] when production-ready
-     start_path: docs
-   ```
-
-3. **Test the Configuration**
-   - Run `npx antora antora-playbook.yml` locally to verify the build works
-   - Check that the new documentation appears correctly in the generated site
-   - Ensure all links and cross-references function properly
-
-
-### Development Guidelines
-
-- Follow the existing Antora playbook configuration patterns
-- Test documentation builds locally before pushing changes
-- Ensure all referenced Git repositories and branches are accessible; i.e. verfy repository access and that branches exist
-- Update branch references from `feature/*` to `main` when components are production-ready
+The project is configured through the `antora-playbook.yml` file.

README.md

@@ -9,12 +9,11 @@ site:
 content:
   edit_url: false # Disable "Edit this page" links
   sources:
-    - url: https://github.com/agentic-layer/documentation.git
-      branches: [main]
-      start_path: home/docs
-    - url: https://github.com/agentic-layer/documentation.git
-      branches: [main]
-      start_path: architecture/docs
+    - url: ./
+      branches: HEAD
+      start_paths:
+        - home/docs
+        - architecture/docs
     - url: https://github.com/agentic-layer/agent-runtime-operator.git
       branches: [main]
       start_path: docs

antora-playbook.yml

@@ -0,0 +1,6 @@
+name: architecture
+title: Agentic Layer Architecture
+version: main
+start_page: ROOT:index.adoc
+nav:
+- modules/ROOT/nav.adoc

architecture/docs/antora.yml

@@ -0,0 +1 @@
+include::architecture:ROOT:partial$architecture-contents.adoc[]

architecture/docs/modules/ROOT/nav.adoc

@@ -0,0 +1,3 @@
+= Agentic Layer Architecture
+
+include::architecture:ROOT:partial$architecture-contents.adoc[]

architecture/docs/modules/ROOT/pages/index.adoc

@@ -0,0 +1,12 @@
+** xref:architecture:introduction:index.adoc[Introduction and Goals]
+// ** xref:architecture:constraints:index.adoc[Architecture Constraints]
+** xref:architecture:context:index.adoc[System Scope and Context]
+// ** xref:architecture:solution-strategy:index.adoc[Solution Strategy]
+** xref:architecture:building-blocks:index.adoc[Building Block View]
+// ** xref:architecture:runtime:index.adoc[Runtime View]
+// ** xref:architecture:deployment:index.adoc[Deployment View]
+** xref:architecture:crosscutting:index.adoc[Cross-cutting Concepts]
+// ** xref:architecture:decisions:index.adoc[Architecture Decisions]
+// ** xref:architecture:quality:index.adoc[Quality Requirements]
+// ** xref:architecture:risks:index.adoc[Risks and Technical Debts]
+** xref:architecture:glossary:index.adoc[Glossary]