feat: add readthedocs.io configuration

[jonpspri]

Summary

• Add .readthedocs.yaml configuration file to enable readthedocs.io integration
• Configure Ubuntu 22.04 build environment with Python 3.11
• Install uv package manager during pre-build phase
• Use existing MkDocs configuration and docs dependencies from pyproject.toml

Test plan

• Verify readthedocs.io can successfully build documentation
• Confirm all MkDocs plugins and dependencies are available during build
• Test that generated documentation matches local MkDocs build

🤖 Generated with Claude Code

[Copilot]

Pull Request Overview

This PR adds Read the Docs configuration to enable automatic documentation hosting and building. The configuration sets up Ubuntu 22.04 with Python 3.11, installs the uv package manager, and configures MkDocs to build documentation using existing project dependencies.

• Adds .readthedocs.yaml configuration file for Read the Docs integration
• Configures build environment with Ubuntu 22.04 and Python 3.11
• Sets up uv package manager installation and MkDocs documentation building

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Copilot]

Installing uv in the pre_create_environment phase but then using pip for package installation creates an inconsistent dependency management approach. Consider either using uv throughout the build process or removing the uv installation if it's not being utilized.

Suggested change

	# Install uv
	- pip install uv

[claude]

Code Review: ReadTheDocs Configuration

Critical Issue Found

The current configuration has a critical issue that will cause the ReadTheDocs build to fail. The problem is with the package installation approach.

🔴 Build Will Fail: Incorrect Installation Method

The configuration uses pip install with extra_requirements but DataBeak requires uv for proper dependency resolution:

python:
  install:
    - method: pip
      path: .
      extra_requirements:
        - docs

Problem: Installing uv via pip in pre_create_environment then using pip for package installation creates inconsistency. DataBeak's build system requires uv for dependency management (see pyproject.toml build-system requirements).

Recommended Solution

Replace the entire .readthedocs.yaml with this corrected version:

---
# Read the Docs configuration file
version: 2

build:
  os: ubuntu-22.04
  tools:
    python: "3.11"
  jobs:
    post_create_environment:
      # Install uv and use it to install dependencies
      - pip install uv
      - uv sync --no-dev
      - uv pip install -e ".[docs]"
    post_install:
      # Verify mkdocs is available
      - mkdocs --version

mkdocs:
  configuration: mkdocs.yml

Additional Issues

1. Missing fail_on_warning: Consider adding fail_on_warning: true under mkdocs section to catch documentation build issues early.

2. No search configuration: ReadTheDocs provides built-in search. Consider if the current MkDocs search plugin configuration needs adjustment.

3. Version pattern missing: No formats section defined. Consider if PDF/EPUB generation is desired.

Security & Performance Considerations

✅ Security: No credentials or sensitive data exposed
✅ Performance: Build configuration is lean and appropriate
⚠️ Compatibility: Ensure ReadTheDocs build environment has sufficient resources for pandas/numpy compilation if needed

Test Coverage Recommendations

The test plan is appropriate but add:

• Verify API documentation auto-generation works (mkdocstrings)
• Test that all MkDocs plugins render correctly
• Validate internal links and cross-references work

Best Practices Alignment

The configuration partially follows DataBeak standards:

• ✅ Uses Python 3.11 as required
• ✅ References existing mkdocs.yml
• ❌ Doesn't properly use uv for installation
• ❌ Missing build verification steps

Summary

This PR adds necessary ReadTheDocs configuration but requires fixes before merging. The installation method must be corrected to use uv properly, matching the project's build system requirements.

[claude]

Code Review for PR #108: Add ReadTheDocs Configuration

Summary

This PR adds basic ReadTheDocs configuration, but there are critical issues that will prevent successful documentation builds.

🔴 Critical Issues

1. Missing uv Package Manager Installation

The configuration uses pip for installation, but DataBeak requires uv as specified in CLAUDE.md. The current approach will fail because:

• The pyproject.toml likely uses uv-specific dependency specifications
• The build process won't have access to the correct dependency resolver

Fix Required:

build:
  os: ubuntu-22.04
  tools:
    python: "3.11"
  jobs:
    pre_install:
      - pip install uv
      - uv sync --group docs

2. Incompatible Installation Method

Using pip install . with extra_requirements: docs won't work correctly with a uv-managed project. ReadTheDocs needs custom commands to use uv.

Recommended Approach:

build:
  os: ubuntu-22.04
  tools:
    python: "3.11"
  commands:
    - pip install uv
    - uv sync --group docs
    - uv run mkdocs build --strict --site-dir $READTHEDOCS_OUTPUT/html

🟡 Important Considerations

3. Missing Static Assets

The mkdocs.yml references:

• favicon: img/favicon.ico
• logo: img/logo.svg
• extra_css: stylesheets/extra.css

These files may not exist, causing build failures. Consider either:

• Adding placeholder files
• Removing these references until assets are created
• Using conditional configuration

4. Build Environment Dependencies

The MkDocs configuration uses advanced plugins (mkdocstrings, mermaid2) that may have system dependencies. Consider adding:

build:
  apt_packages:
    - graphviz  # For potential diagram generation

🟢 Good Practices Observed

• Using Ubuntu 22.04 (stable, well-supported)
• Python 3.11 matches project requirements
• Correct mkdocs.yml reference
• Following ReadTheDocs v2 configuration format

📝 Suggested Complete Configuration

---
# Read the Docs configuration file
version: 2

# Build configuration
build:
  os: ubuntu-22.04
  tools:
    python: "3.11"
  
  # Custom build commands for uv
  commands:
    # Install uv package manager
    - pip install uv
    
    # Install dependencies using uv
    - uv sync --group docs
    
    # Build documentation
    - uv run mkdocs build --strict --site-dir $READTHEDOCS_OUTPUT/html

# Specify the base directory for the project
# (not needed if .readthedocs.yaml is in root)
# base: .

# Build format
formats: 
  - html
  - pdf  # Optional: Enable PDF generation

🔍 Security Review

• No security concerns identified
• Configuration only affects build process
• No secrets or sensitive data exposed

🧪 Testing Recommendations

Before merging:

1. Test the configuration in a ReadTheDocs preview build
2. Verify all MkDocs plugins load correctly
3. Check that generated docs match local builds
4. Validate all navigation links work

📊 Performance Considerations

• Consider caching uv installations between builds if ReadTheDocs supports it
• The current plugin set (especially mkdocstrings) may increase build times

✅ Next Steps

1. Update the configuration to use uv properly
2. Test with ReadTheDocs preview builds
3. Address any missing static assets
4. Consider adding build status badge to README

The core idea is good, but the implementation needs adjustment to work with DataBeak's uv-based dependency management.