docs: add Jekyll configuration for GitHub Pages

danielbentes · claude · danielbentes · commit 7f63ccf29b84 · 2025-12-18T10:58:57.000+01:00
- Add _config.yml with just-the-docs theme - Add index.md landing page with navigation - Add front matter to all documentation files for navigation - Add parent index files for Architecture and Guides sections - Add Gemfile for Jekyll dependencies - Add GitHub Actions workflow for automatic deployment Documentation will be available at https://synaptiai.github.io/siare/ 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,63 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.2'
+          bundler-cache: true
+          working-directory: docs
+
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v4
+
+      - name: Build with Jekyll
+        env:
+          JEKYLL_ENV: production
+          BASE_PATH: ${{ steps.pages.outputs.base_path }}
+        run: |
+          cd docs
+          bundle install
+          bundle exec jekyll build --baseurl "$BASE_PATH"
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
@@ -1,3 +1,9 @@
+---
+layout: default
+title: Configuration
+nav_order: 3
+---
+
 # Configuration Reference
 
 Complete reference for configuring SIARE. All settings can be specified via:
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -1,3 +1,9 @@
+---
+layout: default
+title: Contributing
+nav_order: 10
+---
+
 # Contributing to SIARE
 
 Thank you for your interest in contributing to SIARE! This guide will help you get started.
diff --git a/docs/GLOSSARY.md b/docs/GLOSSARY.md
@@ -1,3 +1,9 @@
+---
+layout: default
+title: Glossary
+nav_order: 8
+---
+
 # SIARE Glossary
 
 Definitions of key terms used throughout the SIARE documentation.
diff --git a/docs/Gemfile b/docs/Gemfile
@@ -0,0 +1,21 @@
+source "https://rubygems.org"
+
+gem "jekyll", "~> 4.3"
+gem "just-the-docs", "~> 0.8"
+
+group :jekyll_plugins do
+  gem "jekyll-seo-tag"
+  gem "jekyll-github-metadata"
+end
+
+# Windows and JRuby does not include zoneinfo files
+platforms :mingw, :x64_mingw, :mswin, :jruby do
+  gem "tzinfo", ">= 1", "< 3"
+  gem "tzinfo-data"
+end
+
+# Performance-booster for watching directories on Windows
+gem "wdm", "~> 0.1", :platforms => [:mingw, :x64_mingw, :mswin]
+
+# Lock http_parser.rb for JRuby
+gem "http_parser.rb", "~> 0.6.0", :platforms => [:jruby]
diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md
@@ -1,3 +1,9 @@
+---
+layout: default
+title: Quickstart
+nav_order: 2
+---
+
 # SIARE Quick Start Guide
 
 Get a self-evolving RAG pipeline running in under 10 minutes.
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
@@ -1,3 +1,9 @@
+---
+layout: default
+title: Troubleshooting
+nav_order: 4
+---
+
 # SIARE Troubleshooting Guide
 
 This guide covers common issues and their solutions when working with SIARE (Self-Improving Agentic RAG Engine).
diff --git a/docs/WHY_SIARE.md b/docs/WHY_SIARE.md
@@ -1,3 +1,9 @@
+---
+layout: default
+title: Why SIARE?
+nav_order: 9
+---
+
 # Why SIARE?
 
 **How SIARE compares to other RAG frameworks and what makes it unique.**
diff --git a/docs/_config.yml b/docs/_config.yml
@@ -0,0 +1,74 @@
+# SIARE Documentation - Jekyll Configuration
+title: SIARE Documentation
+description: Self-Improving Agentic RAG Engine - Documentation
+url: https://synaptiai.github.io
+baseurl: /siare
+
+# Theme - just-the-docs provides clean navigation and search
+remote_theme: just-the-docs/just-the-docs
+
+# Color scheme
+color_scheme: light
+
+# Logo and branding
+logo: "/assets/images/logo.svg"
+
+# Search
+search_enabled: true
+search:
+  heading_level: 2
+  previews: 3
+  preview_words_before: 5
+  preview_words_after: 10
+  tokenizer_separator: /[\s/]+/
+  rel_url: true
+  button: false
+
+# Navigation
+nav_enabled: true
+nav_sort: case_insensitive
+
+# Aux links (top right)
+aux_links:
+  "GitHub":
+    - "https://github.com/synaptiai/siare"
+  "PyPI":
+    - "https://pypi.org/project/siare/"
+
+aux_links_new_tab: true
+
+# Footer
+footer_content: "Copyright &copy; 2024 Synapti AI. Distributed under the MIT License."
+
+# Back to top link
+back_to_top: true
+back_to_top_text: "Back to top"
+
+# Heading anchor links
+heading_anchors: true
+
+# Code highlighting
+highlighter: rouge
+kramdown:
+  syntax_highlighter: rouge
+  syntax_highlighter_opts:
+    block:
+      line_numbers: false
+
+# Collections for organizing content
+collections:
+  guides:
+    output: true
+    permalink: /:collection/:name
+
+# Exclude from processing
+exclude:
+  - Gemfile
+  - Gemfile.lock
+  - README.md
+  - examples/
+
+# Plugins
+plugins:
+  - jekyll-seo-tag
+  - jekyll-github-metadata
diff --git a/docs/architecture/DATA_MODELS.md b/docs/architecture/DATA_MODELS.md
@@ -1,3 +1,10 @@
+---
+layout: default
+title: Data Models
+parent: Architecture
+nav_order: 2
+---
+
 # Complete Data Models Specification
 
 **Version:** 1.1
diff --git a/docs/architecture/SYSTEM_ARCHITECTURE.md b/docs/architecture/SYSTEM_ARCHITECTURE.md
@@ -1,3 +1,10 @@
+---
+layout: default
+title: System Architecture
+parent: Architecture
+nav_order: 1
+---
+
 # SIARE System Architecture
 
 **Version:** 2.0 (Consolidated)
diff --git a/docs/architecture/index.md b/docs/architecture/index.md
@@ -0,0 +1,21 @@
+---
+layout: default
+title: Architecture
+nav_order: 5
+has_children: true
+---
+
+# Architecture
+
+Technical documentation for SIARE's internal architecture and data models.
+
+## Overview
+
+SIARE follows an **open-core architecture**:
+- **siare** (MIT): Core evolution engine, execution, evaluation, gene pool
+- **siare-cloud** (Enterprise): API server, auth, billing, audit logging
+
+## Sections
+
+- [System Architecture](SYSTEM_ARCHITECTURE.html) - Complete system design and component interactions
+- [Data Models](DATA_MODELS.html) - All Pydantic models and their relationships
diff --git a/docs/guides/USE_CASES.md b/docs/guides/USE_CASES.md
@@ -1,3 +1,10 @@
+---
+layout: default
+title: Use Cases
+parent: Guides
+nav_order: 4
+---
+
 # Implementing Domain Use Cases in SIARE
 
 This guide explains how to implement domain-specific use cases in SIARE, using the **clinical trial design** use case as a concrete example. It provides a general pattern that can be applied to any domain requiring autonomous, self-improving multi-agent RAG systems.
diff --git a/docs/guides/custom-extensions.md b/docs/guides/custom-extensions.md
@@ -1,3 +1,10 @@
+---
+layout: default
+title: Custom Extensions
+parent: Guides
+nav_order: 3
+---
+
 # Custom Extensions
 
 Guide to extending SIARE with custom metrics, tools, and constraints.
diff --git a/docs/guides/first-custom-pipeline.md b/docs/guides/first-custom-pipeline.md
@@ -1,3 +1,10 @@
+---
+layout: default
+title: First Custom Pipeline
+parent: Guides
+nav_order: 1
+---
+
 # Your First Custom Pipeline
 
 This guide walks you through building a domain-specific RAG pipeline from scratch. By the end, you'll have a working pipeline tailored to your data and use case.
diff --git a/docs/guides/index.md b/docs/guides/index.md
@@ -0,0 +1,17 @@
+---
+layout: default
+title: Guides
+nav_order: 6
+has_children: true
+---
+
+# Guides
+
+Step-by-step tutorials for building with SIARE.
+
+## Available Guides
+
+- [First Custom Pipeline](first-custom-pipeline.html) - Build your first domain-specific pipeline
+- [Prompt Engineering](prompt-engineering.html) - Write effective prompts for multi-agent systems
+- [Custom Extensions](custom-extensions.html) - Add custom metrics, tools, and constraints
+- [Use Cases](USE_CASES.html) - Real-world implementation examples
diff --git a/docs/guides/prompt-engineering.md b/docs/guides/prompt-engineering.md
@@ -1,3 +1,10 @@
+---
+layout: default
+title: Prompt Engineering
+parent: Guides
+nav_order: 2
+---
+
 # Prompt Engineering for Multi-Agent Systems
 
 Guide to writing effective prompts for SIARE's multi-agent pipelines.
diff --git a/docs/index.md b/docs/index.md
