> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://www.comet.com/docs/opik/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://www.comet.com/docs/opik/_mcp/server.

# Documentation

# Contributing to Documentation

This guide will help you get started with contributing to Opik's documentation.

Before you start, please review our general [Contribution Overview](/contributing/overview) and the [Contributor License Agreement (CLA)](https://github.com/comet-ml/opik/blob/main/CLA.md).

## Documentation Structure

This guide covers how to contribute to the two main parts of Opik's documentation: **This Documentation Website**: Built with [Fern](https://www.buildwithfern.com/) and **Python SDK Reference Documentation**: Built with [Sphinx](https://www.sphinx-doc.org/en/master/).

Here's how you can work with either one:

#### Contributing to this Documentation Website (Fern)

This website (source in `apps/opik-documentation/documentation`) is where our main guides, tutorials, and conceptual documentation live.

### 1. Install Prerequisites

Ensure you have Node.js and npm installed. You can follow the official guide [here](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm/).

### 2. Set up Locally

```bash
cd apps/opik-documentation/documentation

# Install dependencies - Only needs to be run once
npm install

# Optional - Install Python dependencies if updating Jupyter Cookbooks
pip install -r requirements.txt

# Run the documentation website locally
npm run dev


```

Access the local site at `http://localhost:3000`. Changes will update in real-time.

### 3. Make Your Changes

Update content primarily in:

* `fern/docs-v2/`: Main markdown content (like this page).
* `/docs/cookbook`: Source Jupyter Notebooks for the cookbook examples. These are not converted automatically — if you change a notebook, update the matching `fern/docs-v2/**/*.mdx` page in the same PR to keep the published page in step.

Refer to the `docs.yml` file for the overall structure and navigation.

### 4. Submitting Changes

Once you're happy with your changes, commit them and open a Pull Request against the `main` branch of the `comet-ml/opik` repository.

#### Contributing to the Python SDK Reference Documentation (Sphinx)

The Python SDK reference docs (source in `apps/opik-documentation/python-sdk-docs`) are generated from docstrings in the Python codebase using [Sphinx](https://www.sphinx-doc.org/en/master/).

### 1. Install Prerequisites

Ensure you have Python and pip installed. A virtual environment is highly recommended.

### 2. Set up Locally

```bash
cd apps/opik-documentation/python-sdk-docs
# Install dependencies - Only needs to be run once
pip install -r requirements.txt
# Run the python sdk reference documentation locally
make dev
```

Access the local site at `http://127.0.0.1:8000`. Changes will update in real-time as you modify docstrings in the SDK (`sdks/python`) and rebuild.

### 3. Making Changes

Improvements to the SDK reference usually involve updating the Python docstrings directly in the SDK source files located in the `sdks/python` directory.

### 4. Building and Previewing

After editing docstrings, run `make dev` (or `make html` for a one-time build) in the `apps/opik-documentation/python-sdk-docs` directory to regenerate the HTML and preview your changes.

### 5. Submitting Changes

Commit your changes to both the Python SDK source files and any necessary updates in the `python-sdk-docs` directory. Open a Pull Request against the `main` branch.