Documentation Guide¶

This guide explains how to write, build, and maintain documentation for the Dataknobs project.

Structure¶

docs/
├── api/                 # Auto-generated API documentation
├── development/         # Developer guides
├── examples/           # Usage examples
├── overrides/          # MkDocs Material theme overrides
├── packages/           # Package-specific documentation
├── stylesheets/        # Custom CSS
├── user-guide/         # User guides and tutorials
├── changelog.md        # Version history
├── getting-started.md  # Quick start guide
├── index.md           # Home page
├── installation.md    # Installation instructions
├── license.md         # License information
└── migration-guide.md # Migration from legacy package

Building Documentation¶

Prerequisites¶

Install MkDocs and required plugins:

uv pip install mkdocs mkdocs-material mkdocstrings[python] \
  mkdocs-monorepo-plugin mkdocs-awesome-pages-plugin \
  mkdocs-git-revision-date-localized-plugin

Available Scripts¶

The project provides several scripts in the bin/ directory for documentation management:

bin/docs-serve.sh - Start local documentation server with hot reload
bin/docs-build.sh - Build documentation for production
bin/docs-deploy.sh - Deploy documentation to GitHub Pages

Local Development¶

Serve documentation locally with hot reload:

# Using the provided script
./bin/docs-serve.sh

# Or directly with mkdocs
mkdocs serve

The documentation will be available at http://localhost:8000

Building for Production¶

Build the static site:

# Using the provided script
./bin/docs-build.sh

# Or directly with mkdocs
mkdocs build

The built site will be in the site/ directory.

Deploying to GitHub Pages¶

The easiest way to deploy is using the provided deployment script:

# Using the deployment script (recommended)
./bin/docs-deploy.sh

This script will: - Check for uncommitted changes - Build the documentation - Deploy to the gh-pages branch - Provide the URL where docs will be available

Alternatively, deploy directly with mkdocs:

# Direct deployment with mkdocs
mkdocs gh-deploy

Or use the GitHub Actions workflow which automatically deploys on push to main.

Writing Documentation¶

Markdown Extensions¶

The documentation supports various markdown extensions:

Admonitions: !!! note "Title"
Code blocks with syntax highlighting: ```python
Tabs: === "Tab 1"
Tables: Standard markdown tables
Task lists: - [x] Completed task
Footnotes: [^1]
Abbreviations: *[HTML]: Hyper Text Markup Language

API Documentation¶

API documentation is auto-generated from docstrings using mkdocstrings.

To document a module/class/function, use Google-style docstrings:

def example_function(param1: str, param2: int) -> bool:
    """Brief description of the function.

    Longer description providing more details about what
    the function does and how to use it.

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

    Returns:
        Description of return value

    Raises:
        ValueError: When param2 is negative

    Examples:
        >>> example_function("test", 42)
        True
    """
    pass

Then reference it in markdown:

::: module.submodule.example_function

Adding Examples¶

Create example files in docs/examples/ with clear, runnable code:

# Example: Working with Trees

This example demonstrates how to create and manipulate tree structures.

\```python
from dataknobs_structures import Tree

# Create a tree
root = Tree("root")
child = root.add_child("child")

# Print the tree structure
print(root)
\```

## Expected Output

\```
root
└── child
\```

Style Guide¶

Use clear, concise language
Include code examples for all features
Add type hints in examples
Use admonitions for important notes
Keep line length under 80 characters for code blocks
Use semantic versioning in changelog

Contributing¶

When adding new features or making changes:

Update relevant documentation
Add/update examples
Update API documentation docstrings
Update changelog if needed
Test documentation build locally before committing