docs.yml•16 kB
name: Documentation
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
workflow_dispatch:
env:
CARGO_TERM_COLOR: always
jobs:
build-docs:
name: Build Documentation
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v5
- name: Install Rust
uses: dtolnay/rust-toolchain@stable
- name: Install system dependencies
run: |
sudo apt-get update
sudo apt-get install -y build-essential pkg-config libssl-dev
- name: Cache Cargo registry
uses: actions/cache@v4
with:
path: |
~/.cargo/registry
~/.cargo/git
target
key: ${{ runner.os }}-cargo-docs-${{ hashFiles('**/Cargo.lock') }}
- name: Build rustdoc documentation
run: |
# Set rustdoc flags for better documentation
export RUSTDOCFLAGS="--enable-index-page -Zunstable-options --cfg docsrs"
# Build documentation for all workspace members
cargo +nightly doc --workspace --all-features --no-deps
# Create a root index.html that redirects to the main crate
cat > target/doc/index.html << 'EOF'
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>CodeGraph Documentation</title>
<meta http-equiv="refresh" content="0; url=codegraph_core/index.html">
<style>
body {
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
text-align: center;
padding: 2rem;
background: #f5f5f5;
}
.container {
max-width: 600px;
margin: 0 auto;
background: white;
padding: 3rem;
border-radius: 8px;
box-shadow: 0 2px 10px rgba(0,0,0,0.1);
}
h1 { color: #333; }
p { color: #666; margin: 1rem 0; }
a { color: #0066cc; text-decoration: none; }
a:hover { text-decoration: underline; }
</style>
</head>
<body>
<div class="container">
<h1>CodeGraph Documentation</h1>
<p>Redirecting to the main documentation...</p>
<p>If you are not redirected, <a href="codegraph_core/index.html">click here</a>.</p>
</div>
</body>
</html>
EOF
- name: Install mdBook
run: |
curl -L https://github.com/rust-lang/mdBook/releases/download/v0.4.36/mdbook-v0.4.36-x86_64-unknown-linux-gnu.tar.gz | tar xz
sudo mv mdbook /usr/local/bin/
- name: Create mdBook documentation
run: |
# Create book structure
mkdir -p book/src
# Create book.toml
cat > book/book.toml << 'EOF'
[book]
authors = ["CodeGraph Team"]
language = "en"
multilingual = false
src = "src"
title = "CodeGraph User Guide"
description = "Comprehensive guide for CodeGraph embedding system"
[build]
build-dir = "../target/book"
[output.html]
additional-css = ["custom.css"]
git-repository-url = "https://github.com/codegraph/embedding-system"
edit-url-template = "https://github.com/codegraph/embedding-system/edit/main/book/src/{path}"
[output.html.search]
enable = true
[output.html.print]
enable = true
EOF
# Create custom CSS
cat > book/custom.css << 'EOF'
.sidebar { background: #2d3142; }
.sidebar-active { background: #4f5b93 !important; }
h1, h2, h3, h4, h5, h6 { color: #2d3142; }
.hljs { background: #f8f9fa; }
EOF
# Create SUMMARY.md
cat > book/src/SUMMARY.md << 'EOF'
# Summary
[Introduction](./introduction.md)
# User Guide
- [Installation](./installation.md)
- [Quick Start](./quick-start.md)
- [Configuration](./configuration.md)
# Architecture
- [System Overview](./architecture/overview.md)
- [Core Components](./architecture/components.md)
- [Graph Structure](./architecture/graph.md)
- [Vector Search](./architecture/vector-search.md)
# API Reference
- [REST API](./api/rest.md)
- [GraphQL API](./api/graphql.md)
- [Embedding API](./api/embedding.md)
# Performance
- [Benchmarks](./performance/benchmarks.md)
- [Optimization](./performance/optimization.md)
- [Scaling](./performance/scaling.md)
# Development
- [Contributing](./development/contributing.md)
- [Testing](./development/testing.md)
- [Release Process](./development/releases.md)
[FAQ](./faq.md)
EOF
# Create introduction
cat > book/src/introduction.md << 'EOF'
# Introduction
CodeGraph is a high-performance embedding generation system built in Rust using the Candle ML framework. It provides local code analysis and embedding generation capabilities for building code intelligence applications.
## Key Features
- **High Performance**: Built in Rust with optimized ML operations
- **Local Processing**: No data leaves your infrastructure
- **Flexible APIs**: REST and GraphQL interfaces
- **Scalable Architecture**: Designed for enterprise workloads
- **Cross-platform**: Supports Linux, macOS, and Windows
## Architecture Overview
CodeGraph consists of several core components:
- **Core Engine**: Fundamental data structures and algorithms
- **Parser**: Multi-language code parsing using Tree-sitter
- **Graph Store**: Optimized graph storage with RocksDB
- **Vector Engine**: High-performance vector search with FAISS
- **API Layer**: REST and GraphQL endpoints
Continue reading to learn how to install and use CodeGraph in your projects.
EOF
# Create other placeholder files
mkdir -p book/src/architecture book/src/api book/src/performance book/src/development
# Create placeholder content for key sections
echo "# Installation\n\nThis section covers how to install CodeGraph..." > book/src/installation.md
echo "# Quick Start\n\nGet up and running with CodeGraph in minutes..." > book/src/quick-start.md
echo "# Configuration\n\nLearn how to configure CodeGraph for your needs..." > book/src/configuration.md
echo "# System Overview\n\nDetailed architecture overview..." > book/src/architecture/overview.md
echo "# Core Components\n\nExplore the core components..." > book/src/architecture/components.md
echo "# Graph Structure\n\nUnderstanding the graph data model..." > book/src/architecture/graph.md
echo "# Vector Search\n\nHow vector search works in CodeGraph..." > book/src/architecture/vector-search.md
echo "# REST API\n\nComplete REST API reference..." > book/src/api/rest.md
echo "# GraphQL API\n\nComplete GraphQL API reference..." > book/src/api/graphql.md
echo "# Embedding API\n\nEmbedding generation API reference..." > book/src/api/embedding.md
echo "# Benchmarks\n\nPerformance benchmarks and comparisons..." > book/src/performance/benchmarks.md
echo "# Optimization\n\nPerformance optimization techniques..." > book/src/performance/optimization.md
echo "# Scaling\n\nScaling CodeGraph for production..." > book/src/performance/scaling.md
echo "# Contributing\n\nHow to contribute to CodeGraph..." > book/src/development/contributing.md
echo "# Testing\n\nTesting guidelines and procedures..." > book/src/development/testing.md
echo "# Release Process\n\nHow we handle releases..." > book/src/development/releases.md
echo "# FAQ\n\nFrequently asked questions..." > book/src/faq.md
# Build the book
cd book && mdbook build
- name: Generate OpenAPI documentation
run: |
# Create OpenAPI spec from code comments or annotations
# This would typically be generated from your actual API code
mkdir -p target/openapi
cat > target/openapi/openapi.yaml << 'EOF'
openapi: 3.0.0
info:
title: CodeGraph API
version: 1.0.0
description: RESTful API for CodeGraph embedding system
license:
name: MIT OR Apache-2.0
servers:
- url: http://localhost:8080
description: Development server
paths:
/health:
get:
summary: Health check endpoint
responses:
'200':
description: Service is healthy
/embed:
post:
summary: Generate embeddings for code
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
code:
type: string
description: Source code to embed
language:
type: string
description: Programming language
responses:
'200':
description: Embeddings generated successfully
content:
application/json:
schema:
type: object
properties:
embeddings:
type: array
items:
type: number
EOF
- name: Combine all documentation
run: |
# Create a unified documentation site structure
mkdir -p target/final-docs
# Copy rustdoc
cp -r target/doc target/final-docs/api
# Copy mdBook
cp -r target/book target/final-docs/guide
# Copy OpenAPI
cp -r target/openapi target/final-docs/openapi
# Create main index
cat > target/final-docs/index.html << 'EOF'
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>CodeGraph Documentation Hub</title>
<style>
body {
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
margin: 0;
padding: 2rem;
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
color: white;
min-height: 100vh;
}
.container {
max-width: 800px;
margin: 0 auto;
}
h1 {
font-size: 3rem;
margin-bottom: 1rem;
text-align: center;
}
.subtitle {
text-align: center;
font-size: 1.2rem;
opacity: 0.9;
margin-bottom: 3rem;
}
.docs-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
gap: 2rem;
margin: 2rem 0;
}
.doc-card {
background: rgba(255,255,255,0.1);
padding: 2rem;
border-radius: 12px;
text-align: center;
transition: transform 0.3s ease;
backdrop-filter: blur(10px);
}
.doc-card:hover {
transform: translateY(-5px);
}
.doc-card h3 {
margin-top: 0;
font-size: 1.5rem;
}
.doc-card p {
opacity: 0.9;
margin: 1rem 0;
}
.doc-link {
display: inline-block;
padding: 0.8rem 1.5rem;
background: rgba(255,255,255,0.2);
color: white;
text-decoration: none;
border-radius: 8px;
transition: background 0.3s ease;
}
.doc-link:hover {
background: rgba(255,255,255,0.3);
}
</style>
</head>
<body>
<div class="container">
<h1>CodeGraph</h1>
<div class="subtitle">High-performance code embedding system</div>
<div class="docs-grid">
<div class="doc-card">
<h3>📚 User Guide</h3>
<p>Complete user documentation including installation, configuration, and usage examples.</p>
<a href="guide/index.html" class="doc-link">Read Guide</a>
</div>
<div class="doc-card">
<h3>🔧 API Reference</h3>
<p>Comprehensive Rust API documentation generated from source code.</p>
<a href="api/index.html" class="doc-link">Browse API</a>
</div>
<div class="doc-card">
<h3>🌐 REST API</h3>
<p>Interactive OpenAPI documentation for the REST endpoints.</p>
<a href="openapi/openapi.yaml" class="doc-link">View Spec</a>
</div>
</div>
</div>
</body>
</html>
EOF
- name: Upload documentation artifacts
uses: actions/upload-artifact@v4
with:
name: documentation
path: target/final-docs/
retention-days: 30
deploy-docs:
name: Deploy Documentation
runs-on: ubuntu-latest
needs: build-docs
if: github.ref == 'refs/heads/main'
steps:
- name: Download documentation artifacts
uses: actions/download-artifact@v3
with:
name: documentation
path: docs-site
- name: Deploy to GitHub Pages
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./docs-site
force_orphan: true
docs-link-check:
name: Documentation Link Check
runs-on: ubuntu-latest
needs: build-docs
steps:
- name: Download documentation artifacts
uses: actions/download-artifact@v3
with:
name: documentation
path: docs-site
- name: Link Checker
uses: lycheeverse/lychee-action@v2.6.1
with:
args: --verbose --no-progress 'docs-site/**/*.html' 'docs-site/**/*.md'
fail: true
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
docs-accessibility:
name: Documentation Accessibility Check
runs-on: ubuntu-latest
needs: build-docs
steps:
- name: Download documentation artifacts
uses: actions/download-artifact@v3
with:
name: documentation
path: docs-site
- name: Setup Node.js
uses: actions/setup-node@v6
with:
node-version: '18'
- name: Install axe-core CLI
run: npm install -g @axe-core/cli
- name: Serve documentation locally
run: |
cd docs-site
python3 -m http.server 8000 &
sleep 5
- name: Run accessibility tests
run: |
axe http://localhost:8000 --exit