Version:

This project is part of pgEdge Labs and is under active development. APIs and features may change without notice.

pg_semantic_cache Documentation

This directory contains the source files for the pg_semantic_cache documentation, built with MkDocs and the Material theme.

Building the Documentation

Prerequisites

Python 3.8+ with pip installed.

Setup

Install dependencies:
```
pip install -r docs-requirements.txt
```
Preview documentation locally:
```
mkdocs serve
```

Then open http://127.0.0.1:8000 in your browser.

Build static site:
```
mkdocs build
```

Output will be in the site/ directory.

Documentation Structure

docs/
├── index.md                    # Home page
├── installation.md             # Installation guide
├── configuration.md            # Configuration guide
├── use_cases.md               # Practical examples
├── monitoring.md              # Monitoring and optimization
├── FAQ.md                     # Frequently asked questions
├── functions/                 # Function reference
│   ├── index.md              # Functions overview
│   ├── cache_query.md        # cache_query() documentation
│   ├── get_cached_result.md  # get_cached_result() documentation
│   └── ...                   # Additional function docs
├── img/                       # Images and assets
└── stylesheets/              # Custom CSS (if needed)

Writing Guidelines

Style

Use clear, concise language
Include practical examples
Add code blocks with syntax highlighting
Use admonitions for warnings, tips, notes
Keep sections focused and scannable

Admonitions

!!! note
    This is a note

!!! tip "Pro Tip"
    This is a tip with custom title

!!! warning
    This is a warning

!!! danger "Critical"
    This is a danger message

Code Blocks

```sql
-- SQL example
SELECT * FROM semantic_cache.cache_stats();
```

```python
# Python example
import psycopg2
```

Tabs

=== "PostgreSQL"
    ```sql
    SELECT 1;
    ```

=== "Python"
    ```python
    print("Hello")
    ```

Deployment

Documentation can be deployed to:

GitHub Pages: mkdocs gh-deploy
Read the Docs: Connect repository
Custom hosting: Deploy site/ directory

Contributing

When adding documentation:

Follow existing structure and style
Test locally with mkdocs serve
Update mkdocs.yml navigation if adding new pages
Ensure all internal links work
Add examples where helpful