Writing documentation¶

This directory contains the source files for Nyctea's documentation, built with Zensical.

Building the Documentation¶

Prerequisites¶

Install Zensical:

pip install zensical mkdocstrings[python]

Or with uv:

uv add --dev zensical mkdocstrings-python

Local Development¶

Serve the documentation locally with auto-reload:

zensical serve

Or with optional flags:

zensical serve --open  # Open browser automatically
zensical serve --dev-addr localhost:3000  # Use different port

Then open http://localhost:8000 in your browser (or the custom port you specified).

Building Static Site¶

Build the static documentation site:

zensical build

The built site will be in the site/ directory.

Documentation Structure¶

docs/
├── index.md              # Homepage
├── api/                  # API reference (auto-generated from docstrings)
│   ├── index.md
│   ├── engine.md         # Validation engine
│   ├── registry.md       # Function registry
│   ├── schema.md         # Schema models
│   └── ingest.md         # Data ingestion
└── user-guide/               # User guides (manually written)
    ├── index.md
    ├── quickstart.md
    ├── registry.md
    └── ...

Writing Documentation¶

Module Docstrings¶

Module docstrings should use Google style:

"""Brief description.

Extended description with more details.

Example:
    Usage example::

        from nyctea import validate
        result = validate(df, schema, registry)

Note:
    Important notes or warnings.

Args:
    param1: Description of param1.
    param2: Description of param2.

Returns:
    Description of return value.

Raises:
    ValueError: When something goes wrong.
"""

Function Docstrings¶

Functions should also use Google style:

def validate(df, schema, registry):
    """Validate a DataFrame according to schema.

    Args:
        df: Input DataFrame or LazyFrame.
        schema: SchemaModel defining validation rules.
        registry: FunctionRegistry with parsers and checks.

    Returns:
        ValidationResult with data, errors, and report.

    Raises:
        SchemaResolutionError: If columns cannot be resolved.

    Example:
        >>> result = validate(df, schema, registry)
        >>> print(result.report.summary())
    """

Markdown Files¶

Guide pages use standard Markdown with some extensions:

• Admonitions for notes/warnings
• Code blocks with syntax highlighting
• Tables for structured data
• Links to other pages and API docs

Example:

# Page Title

Brief introduction.

## Section

Content with **bold** and *italic*.

```python
# Code example
result = validate(df, schema, registry)
```

!!! note
    This is an admonition box.

See the [API reference](../api/index.md) for more details.

API Reference¶

API reference pages use Zensical's ::: syntax to auto-generate documentation from docstrings:

# Module Name

## FunctionName

::: module.path.FunctionName
    options:
      show_root_heading: true
      heading_level: 3

Zensical will automatically extract docstrings, signatures, and type annotations.

Tips¶

1. Keep docstrings updated - They're the source of truth for API docs
2. Use examples - Code examples in docstrings appear in the API reference
3. Link liberally - Link to related pages and API docs
4. Test locally - Always preview with zensical serve before committing
5. Check links - Zensical will warn about broken internal links

Configuration¶

Documentation configuration is in zensical.toml at the project root. Key settings:

• Theme - Modern Material-inspired theme with dark mode
• Features - Code highlighting, copy buttons, search, navigation
• Navigation - Site structure defined in the nav array
• Fonts - Custom font configuration

Contributing¶

When adding new modules or functions:

1. Add Google-style docstrings to the code
2. Add the module to docs/api/ if needed
3. Update navigation in zensical.toml
4. Add user guide pages for major features
5. Test locally with zensical serve
6. Submit PR with both code and docs