Building and Maintaining Documentation¶

This guide explains how to build, test, and maintain the Marin documentation.

Prerequisites¶

Before you begin, ensure you have the following installed:

Python 3.11 or higher
uv (Python package manager)
Git

Installation¶

Install the documentation dependencies:
```
uv sync --package marin --group dev
```
Marin's dev group includes the docs tooling, and this is the same install command used by the docs CI workflow and the general contributor setup.

Building Documentation¶

Local Development¶

Start the local development server:
```
uv run mkdocs serve
```
This will start a local server at http://127.0.0.1:8000 where you can preview your changes in real-time.
Build the documentation:
```
uv run mkdocs build
```
This will create a site directory containing the built documentation.

Production Build¶

For production builds, use:

uv run mkdocs build --clean

Documentation Structure¶

The documentation follows the Diátaxis framework with four main sections:

Tutorials (docs/tutorials/)
Step-by-step guides
Getting started guides
Learning-oriented content
Technical References (docs/references/)
API documentation
Configuration options
Technical specifications
Explanations (docs/explanations/)
Background information
Design decisions
Best practices

We deviate slightly, adding design docs as a fifth section.

Writing Documentation¶

Markdown Guidelines¶

Use proper heading hierarchy:
```
# Main Title
## Section
### Subsection
```

Include code blocks with language specification:

```python
def example():
    return "Hello, World!"

```

Use admonitions for important notes:

!!! note
    This is an important note.

API Documentation¶

For Python code documentation: 1. Use Google-style docstrings 2. Include type hints 3. Document parameters and return values

Example:

def process_data(data: List[str]) -> Dict[str, int]:
    """Process a list of strings into a frequency dictionary.

    Args:
        data: List of strings to process

    Returns:
        Dictionary mapping strings to their frequencies
    """
    return Counter(data)

Testing Documentation¶

Check for broken links:
```
uv run mkdocs build --strict
```
Check GitHub source links after moving, deleting, or relinking docs pages:
```
uv run python infra/check_docs_source_links.py
```
Validate markdown:
```
uv run mkdocs build --strict --verbose
```

Deployment¶

The documentation is automatically deployed when changes are pushed to the main branch. The deployment process:

Builds the documentation
Validates the build
Deploys to the configured hosting service

Contributing¶

Create a new branch for your changes
Make your changes
Preview the docs locally with uv run mkdocs serve
Run ./infra/pre-commit.py --all-files --fix
Run uv run mkdocs build --strict
Submit a pull request whose body references an issue with Fixes #NNNN or Part of #NNNN

For the full contributor workflow, including targeted test guidance, see Contributing to Marin.

Common Issues¶

Broken Links¶

Use relative links for internal documentation
Use absolute URLs for external links
Run uv run python infra/check_docs_source_links.py after moving, deleting, or relinking docs pages that reference GitHub paths
Run uv run mkdocs build --strict after docs edits to catch navigation and Markdown link failures

Build Errors¶

Check for syntax errors in markdown
Verify all required dependencies are installed
Check for missing files or incorrect paths