# VIPR Sphinx Documentation

Sphinx documentation for the VIPR Framework, deployed at [vipr-docs.pages.dev](https://vipr-docs.pages.dev).

## Setup

Use a Python environment that can import the Python sibling repositories.

```bash
cd vipr-framework/docs-sphinx
pip install -r requirements-docs.txt
```

`vipr-core`, `vipr-api`, and `vipr-reflectometry-plugin` must be checked out as sibling directories (same parent as `vipr-framework/`). They are added to `sys.path` in `conf.py`, but Sphinx still needs the packages and their runtime dependencies importable in the active Python environment.

`vipr-frontend` is not imported by Sphinx directly.

The editable installs are recommended because:
- `autodoc` imports modules from all three repositories
- `celery.contrib.sphinx` is used to document Celery tasks
- `scripts/generate_api_route_docs.py` imports the real FastAPI routers and uses the runtime Cement registry to generate the HTTP route overview

## Build

```bash
cd vipr-framework/docs-sphinx
sphinx-apidoc -o docs/api/vipr-core         ../../vipr-core/vipr
sphinx-apidoc -o docs/api/vipr-api          ../../vipr-api/vipr_api ../../vipr-api/vipr_api/main.py
sphinx-apidoc -o docs/api/reflectometry     ../../vipr-reflectometry-plugin/vipr_reflectometry
python scripts/generate_api_route_docs.py
sphinx-build -b html . _build/html
```

Open `_build/html/index.html` in a browser to preview locally.

`generate_api_route_docs.py` intentionally uses the runtime controller/route registry. Expect VIPR/Cement plugin initialization logs during this step.

## Regenerate API reference (when new modules are added)

```bash
cd vipr-framework/docs-sphinx
sphinx-apidoc -o docs/api/vipr-core         ../../vipr-core/vipr
sphinx-apidoc -o docs/api/vipr-api          ../../vipr-api/vipr_api ../../vipr-api/vipr_api/main.py
sphinx-apidoc -o docs/api/reflectometry     ../../vipr-reflectometry-plugin/vipr_reflectometry
python scripts/generate_api_route_docs.py
```

This overwrites the auto-generated `.rst` files in `docs/api/` and refreshes `docs/generated/api_routes.md`. Commit the result.

`vipr_api.main` is excluded from `sphinx-apidoc` because importing it boots the FastAPI app and triggers VIPR controller discovery as a side effect. The generated `docs/generated/api_routes.md` page covers the mounted HTTP routes separately.

## Deploy to Cloudflare Pages

1. Regenerate the derived docs content and build the HTML:
   ```bash
   cd vipr-framework/docs-sphinx
   sphinx-apidoc -o docs/api/vipr-core         ../../vipr-core/vipr
   sphinx-apidoc -o docs/api/vipr-api          ../../vipr-api/vipr_api ../../vipr-api/vipr_api/main.py
   sphinx-apidoc -o docs/api/reflectometry     ../../vipr-reflectometry-plugin/vipr_reflectometry
   python scripts/generate_api_route_docs.py
   sphinx-build -b html . _build/html
   ```

2. Create a ZIP from the HTML output (**zip the contents, not the folder**):
   ```bash
   cd _build/html && zip -r ../../../vipr-docs.zip . && cd ../../..
   ```

3. Go to [Cloudflare Dashboard → Pages → vipr-docs](https://dash.cloudflare.com) → **Create deployment**
4. Upload `vipr-docs.zip`
5. The new version is live at [vipr-docs.pages.dev](https://vipr-docs.pages.dev)

## How it works

| Component | Role |
|---|---|
| `conf.py` | Sphinx config; adds vipr-core, vipr-api, and vipr-reflectometry-plugin to `sys.path` |
| `sphinx.ext.autodoc` | Reads Python docstrings and renders them as API reference |
| `sphinx.ext.napoleon` | Parses Google-style / NumPy-style docstrings |
| `celery.contrib.sphinx` | Makes Celery task-decorated callables appear as documentable tasks |
| `myst_parser` | Allows writing documentation in Markdown (`.md`) instead of reStructuredText |
| `furo` | Theme with dark/light mode and VIPR brand colors |
| `docs/api/` | Auto-generated `.rst` files (via `sphinx-apidoc`) — one file per module |
| `scripts/generate_api_route_docs.py` | Generates the combined HTTP route overview for auto-generated Cement routes and manual FastAPI routes |
| `docs/frontend/` | Hand-written frontend architecture and route documentation |
