# Documentation Server Help

The CAL Documentation Server provides a central location to store project documentation
with automatic indexing and support for versioned documentation.

Anyone can easily add their documentation by choosing a unique project name.

## Supported Documentation Types

The documentation server supports:

- **Static HTML sites** - Pre-built HTML documentation (e.g., from Sphinx, MkDocs, pdoc)
- **Markdown files** - `.md` files rendered on-the-fly with syntax highlighting
- **Mixed content** - Combination of HTML and markdown files

### Requirements

Documentation must be self-contained in a directory with either `index.html` or `index.md`
at the root.

## Configuration with docinfo

Add a `docinfo` file to your documentation root to customize 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 directory name)
- `description` - Description text shown under the project name
- `noindex` - Set to `true` to hide from index (still accessible via direct URL)

**Logo support:**

Place an image file named `docinfo.png`, `docinfo.jpg`, or `docinfo.svg` in the same
directory to display a logo on the index page.

**Example docinfo.json:**

```json
{
  "name": "My Project",
  "description": "A comprehensive guide to using My Project",
  "noindex": false
}
```

## Version Management

The server supports versioned documentation with automatic "Latest" link handling.

### Directory Naming Convention

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

The server automatically:

- Detects all versions based on directory names (e.g., `my-project-*`)
- Filters out beta/alpha/rc versions when determining "Latest"
- Redirects the unversioned URL (`/my-project/`) to the latest stable version
- Sorts versions using semantic versioning

**Example directory structure:**

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

In this example, accessing `/my-project/` serves content from `my-project-2.1.0/` (the
latest non-beta version).

## Downloading Documentation

You can download any project version as a zip file using a simple URL:

```
/{project}-{version}-docs.zip
```

For example:

```bash
# Download a specific version
curl -o docs.zip http://example.com/my-project-1.2.3-docs.zip

# Download the latest version
curl -o docs.zip http://example.com/my-project-latest-docs.zip
```

This matches the standard filename convention used when uploading documentation.

The REST API also provides a download endpoint at `/api/download/{project}/{version}`.

## REST API

The server provides a REST API for programmatic access to documentation.

### cal-docs-client

For command-line access to the API, use the `cal-docs-client` tool:

```bash
# Install the client
pip install cal-docs-client

# List projects
cal-docs-client list

# Upload documentation
cal-docs-client upload my-project-1.0.0-docs.zip
```

See the [cal-docs-client documentation](https://example.com/) for full usage.

### Endpoints

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

### Authentication

Upload and delete require token authentication via the `X-Token` header. Contact your
administrator to obtain a token. Delete operations additionally require the token to have
delete permission.

```
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"

# Download latest version as zip
curl -o docs.zip http://example.com/api/download/my-project/latest

# Download specific version
curl -o docs.zip http://example.com/api/download/my-project/1.2.3

# Upload documentation (requires token)
curl -X POST -H "X-Token: your-token" \
     -F "file=@my-project-1.0.0-docs.zip" \
     http://example.com/api/upload

# Delete a specific version (requires token with delete permission)
curl -X DELETE -H "X-Token: your-token" \
     http://example.com/api/delete/my-project/1.2.3
```

## Uploading Documentation

### Zip File Naming

When uploading via the API, name your zip file to indicate the project and version:

- `my-project-1.2.3.zip`
- `my-project-1.2.3-docs.zip`

The server extracts the project name and version from the filename.

### Using GitLab CI

Upload documentation automatically as part of your CI/CD pipeline:

```yaml
upload_docs:
  stage: deploy
  only:
    - tags
  script:
    - zip -r my-project-${CI_COMMIT_TAG}-docs.zip ./html
    - curl -X POST -H "X-Token: ${DOC_SERVER_TOKEN}" \
           -F "file=@my-project-${CI_COMMIT_TAG}-docs.zip" \
           "${DOC_SERVER_URL}/api/upload"
```

## Tips

- Only upload docs from tagged releases or manual jobs, not every commit
- Use semantic versioning for directory names (e.g., `1.2.3`, not `v1.2.3`)
- Beta/alpha versions should include the suffix (e.g., `2.0.0b1`, `3.0.0-alpha`)
- The server caches the index for 20 seconds, so changes may take a moment to appear
