apflow Documentation

This repository contains the documentation website for apflow, built with MkDocs and Material for MkDocs.

Overview

This is a standalone documentation project that serves the developer documentation for the apflow library. The documentation source files are maintained in the main apflow repository under the docs/ directory.

Quick Start

Choose one of the following methods to run the documentation locally.

Option 1: Docker (Recommended)

Prerequisites:

Docker
Docker Compose

Start the server:

docker-compose up

The documentation will be available at http://localhost:8000.

Tip

Docker Usage Guide

Content Changes: Modifications to docs/*.md files are applied automatically (Live Reload).
Configuration Changes: Modifications to mkdocs.yml usually reload automatically. If not, run docker-compose restart.
Dependency Changes: If you modify requirements.txt or Dockerfile, you must rebuild the image:
```
docker-compose up --build
```

Option 2: Local Development

Prerequisites:

Python 3.10 or higher (3.12+ recommended)
pip

1. Setup:

Use the setup script to create a virtual environment and install dependencies:

./scripts/setup.sh

2. Start the server:

Use the start script to launch the development server:

./scripts/start.sh

The documentation will be available at http://localhost:8000.

Configuration

Port Configuration

You can configure the application port using a .env file or environment variables. This works for both Docker and Local Development.

Create configuration file:
```
cp .env.example .env
```
Edit .env and set your desired port, e.g., PORT=8001.

Or use environment variables:

Docker:

PORT=8001 docker-compose up

Local:

export PORT=8001
./scripts/start.sh

Advanced Usage

Manual Setup

If you prefer not to use the scripts:

Create a virtual environment: python -m venv .venv
Activate it: source .venv/bin/activate
Install dependencies: pip install -r requirements.txt
Sync docs: python scripts/sync_docs.py
Serve: mkdocs serve

Building Documentation

For Development (Live Preview):

# Start development server with live reload
./scripts/start.sh

This starts a development server at http://localhost:8000 with automatic reload on file changes.

For Production (Static Build):

# Build and deploy to site/ directory (default, recommended)
./scripts/deploy.sh

# Or just build without deploying
DEPLOY_PATH="" ./scripts/deploy.sh

# Or use the build script directly
./scripts/build_with_versioning.sh

# Or traditional mkdocs build (no versioning)
mkdocs build

Output Locations:

Default: site/0.2.0/, site/latest/ (when using ./scripts/deploy.sh)
Server: /var/www/html/0.2.0/ (when DEPLOY_PATH=/var/www/html)
All use the same site/ directory convention (MkDocs standard)

Syncing Documentation

The documentation source files are maintained in the main apflow repository.

Local Sync:
```
python scripts/sync_docs.py
```

CI/CD Sync:

# Syncs and forces overwrite, skipping website-specific files
python scripts/sync_docs.py --ci --path ../apflow

Deployment

The documentation is automatically deployed to GitHub Pages when changes are pushed to the main branch via GitHub Actions. See DEPLOYMENT.md for details.

To manually deploy:

mkdocs gh-deploy

Project Structure

apflow-docs/
├── docs/                    # Documentation source files (Markdown)
├── mkdocs.yml              # MkDocs configuration
├── requirements.txt        # Python dependencies
├── Dockerfile              # Docker image definition
├── docker-compose.yml      # Docker Compose configuration
├── scripts/
│   ├── setup.sh            # Setup script
│   ├── start.sh            # Start script
│   └── sync_docs.py        # Documentation sync script
└── README.md               # This file

Contributing

Make changes to the documentation files in the main apflow repository's docs/ directory.
Sync the changes to this repository.
Test locally.
Commit and push.

License

Apache-2.0

aipartnerup/apflow-docs