# Documentation Server Help

The CAL Documentation Server provides a central index for project documentation with
automatic indexing and support for versioned documentation. It operates in one of two
modes: **GitLab Pages mode** or **filesystem mode**.

## GitLab Pages Mode

In this mode the server indexes documentation from GitLab Pages sites within one or more
GitLab groups. Each project in the group is expected to publish its docs to GitLab Pages
with the following layout:

```
public/
  index.html          (redirects to latest/)
  latest/             (copy of the newest version)
  {version}/          (e.g. 1.2.3/)
    index.html
    docinfo.yaml      (optional: name, description, logo)
```

The index is refreshed automatically in the background by polling GitLab at a configurable
interval. The latest stable version (excluding beta/alpha/rc) is shown as "Latest".

### Downloading Documentation

You can download any project version as a zip. The server fetches the files directly
from the GitLab repository and packages them for you:

```bash
# Convenient URL (use -J to save with the resolved version name)
curl -OJ http://example.com/my-project-latest-docs.zip
curl -OJ http://example.com/my-project-1.2.3-docs.zip

# REST API
curl -OJ http://example.com/api/download/my-project/latest
curl -OJ http://example.com/api/download/my-project/1.2.3
```

Using `-J` tells curl to use the server's suggested filename from the `Content-Disposition`
header, so `latest` resolves to the actual version number (e.g. `my-project-2.0.0-docs.zip`).

### Publishing Docs via GitLab CI

Publish documentation automatically as part of your CI/CD pipeline using GitLab Pages:

```yaml
pages:
  stage: deploy
  only:
    - tags
  script:
    - mkdir -p public/${CI_COMMIT_TAG}
    - cp -r ./html/. public/${CI_COMMIT_TAG}/
    - cp -r ./html/. public/latest/
    - echo '<meta http-equiv="refresh" content="0;url=latest/">' > public/index.html
  artifacts:
    paths:
      - public
```

Use semantic versioning for version directories (e.g., `1.2.3`, not `v1.2.3`).
Beta/alpha/rc versions should include the suffix (e.g., `2.0.0b1`, `3.0.0-alpha`) — they
will still appear in the version list but won't be shown as "Latest".

## Filesystem Mode

In this mode the server serves documentation directly from a local directory. Each project
is a subdirectory with optional versioned subdirectories.

### Directory Naming Convention

- **Unversioned:** `my-project/` (optional if versioned dirs exist)
- **Versioned:** `my-project-1.2.3/`, `my-project-2.0.0/`, etc.

```
docs/
├── my-project-1.0.0/
├── my-project-2.0.0/
├── my-project-2.1.0/
└── my-project-3.0.0b1/    (excluded from "Latest")
```

The server redirects `/my-project/` to the latest non-beta version automatically.

### Supported Documentation Types

- **Static HTML** — Pre-built HTML sites (Sphinx, MkDocs, pdoc, etc.)
- **Markdown** — `.md` files rendered on-the-fly with syntax highlighting
- **Mixed** — Any combination of HTML and markdown

Documentation must have either `index.html` or `index.md` at its root.

### Uploading Documentation

Upload a zip file via the REST API:

```bash
curl -X POST -H "X-Token: your-token" \
     -F "file=@my-project-1.0.0-docs.zip" \
     http://example.com/api/upload
```

Name the zip file `{project}-{version}.zip` or `{project}-{version}-docs.zip`. The server
extracts the project name and version from the filename automatically.

### Downloading Documentation

Download any version as a zip:

```bash
# Convenient URL
curl -o docs.zip http://example.com/my-project-1.2.3-docs.zip
curl -o docs.zip http://example.com/my-project-latest-docs.zip

# REST API
curl -o docs.zip http://example.com/api/download/my-project/1.2.3
curl -o docs.zip http://example.com/api/download/my-project/latest
```

## Configuration with docinfo

Add a `docinfo` file to your documentation root (or version directory) to customise how
it appears in the index.

**Supported formats:** `docinfo.json`, `docinfo.json5`, `docinfo.yaml`, `docinfo.yml`

**Available fields:**

- `name` — Display name shown in index (defaults to project/directory name)
- `description` — Description text shown under the project name
- `noindex` — Set to `true` to hide from the index (still accessible via direct URL)

**Logo support:**

Place `docinfo.png`, `docinfo.jpg`, or `docinfo.svg` alongside the docinfo file to
display a logo on the index page.

**Example docinfo.yaml:**

```yaml
name: My Project
description: A comprehensive guide to using My Project
```

## REST API

| Method | Endpoint | Available in | Description |
|--------|----------|-------------|-------------|
| GET | `/api/version` | Both | Returns product name and version |
| GET | `/api/spec` | Both | Returns OpenAPI 3.0 specification |
| GET | `/api/projects` | Both | Lists all projects and versions |
| GET | `/api/projects?search=term` | Both | Filter projects by name |
| GET | `/api/download/{project}/{version}` | Both | Download project as zip |
| POST | `/api/upload` | Filesystem | Upload documentation (requires auth) |
| DELETE | `/api/delete/{project}/{version}` | Filesystem | Delete a version (requires auth) |

### Authentication

Upload and delete require a token via the `X-Token` header. Contact your administrator to
obtain a token.

```
X-Token: your-secret-token
```

### Examples

```bash
# List all projects
curl http://example.com/api/projects

# Search projects
curl "http://example.com/api/projects?search=my-project"
```
