ReadTheDocs Setup Guide

This document explains how to set up and deploy the kicad-sch-api documentation on ReadTheDocs.

What’s Configured

The repository is fully configured for ReadTheDocs deployment:

Configuration Files

  • .readthedocs.yaml - ReadTheDocs build configuration

    • Python 3.11 build environment

    • Installs uv package manager

    • Uses docs/conf.py for Sphinx configuration

    • Generates PDF and EPUB formats

  • docs/conf.py - Sphinx configuration

    • Sphinx RTD theme for professional styling

    • MyST parser for markdown support

    • Auto-generated API docs from docstrings

    • Napoleon extension for Google/NumPy style docstrings

  • docs/index.rst - Main documentation index

    • Navigation structure

    • Quick example and installation guide

    • Links to all documentation sections

  • docs/api/modules.rst - API reference structure

    • Auto-generated from Python docstrings

    • Organized by module (collections, parsers, etc.)

Documentation Structure

docs/
β”œβ”€β”€ conf.py                    # Sphinx configuration
β”œβ”€β”€ index.rst                  # Main index (entry point)
β”œβ”€β”€ api/
β”‚   └── modules.rst           # API reference
β”œβ”€β”€ _static/                   # Static assets (images, CSS)
β”œβ”€β”€ _templates/                # Custom templates (if needed)
β”œβ”€β”€ README.md                  # Documentation index
β”œβ”€β”€ GETTING_STARTED.md         # Beginner's guide
β”œβ”€β”€ WHY_USE_THIS_LIBRARY.md   # Value proposition
β”œβ”€β”€ API_REFERENCE.md           # Complete API docs
β”œβ”€β”€ RECIPES.md                 # Practical examples
└── ARCHITECTURE.md            # Internal design

Local Testing

Build Documentation Locally

# Install docs dependencies
uv pip install -e ".[docs]"

# Build HTML documentation
cd docs
uv run sphinx-build -b html . _build/html

# View in browser
open _build/html/index.html  # macOS
xdg-open _build/html/index.html  # Linux
start _build/html/index.html  # Windows

Build Other Formats

# PDF (requires LaTeX)
uv run sphinx-build -b latex . _build/latex
cd _build/latex && make

# EPUB
uv run sphinx-build -b epub . _build/epub

ReadTheDocs Deployment

Initial Setup

  1. Import Project on ReadTheDocs

    • Go to https://readthedocs.org/

    • Sign in with GitHub account

    • Click β€œImport a Project”

    • Select circuit-synth/kicad-sch-api

  2. Configure Project

    • Project will auto-detect .readthedocs.yaml

    • Default branch: main

    • Documentation URL: https://kicad-sch-api.readthedocs.io/

  3. Build Settings (auto-configured via .readthedocs.yaml)

    • βœ… Build documentation on every commit

    • βœ… Build documentation on pull requests

    • βœ… Generate PDF and EPUB downloads

Webhook Integration

ReadTheDocs automatically sets up GitHub webhooks to trigger builds on:

  • Pushes to main branch

  • New tags/releases

  • Pull requests (for preview builds)

Custom Domain (Optional)

If you want to use a custom domain:

  1. In ReadTheDocs Admin β†’ Domains

  2. Add custom domain (e.g., docs.circuit-synth.com)

  3. Add CNAME record in DNS pointing to readthedocs.io

Adding New Documentation

Adding Markdown Pages

  1. Create new .md file in docs/ directory

  2. Add to docs/index.rst table of contents:

.. toctree::
   :maxdepth: 2
   :caption: Your Section

   YOUR_NEW_FILE

  1. Commit and push - ReadTheDocs will rebuild automatically

Adding New API Modules

New Python modules are auto-discovered if they have docstrings. To explicitly add:

  1. Edit docs/api/modules.rst

  2. Add module reference:

New Module
~~~~~~~~~~

.. automodule:: kicad_sch_api.your.new.module
   :members:
   :undoc-members:
   :show-inheritance:

Troubleshooting

Build Failures

Check ReadTheDocs build logs:

  1. Go to https://readthedocs.org/projects/kicad-sch-api/

  2. Click β€œBuilds” tab

  3. View latest build log

Common issues:

  • Missing dependencies: Add to pyproject.toml under [project.optional-dependencies.docs]

  • Import errors: Ensure module can be imported in build environment

  • MyST errors: Check markdown syntax in .md files

Local Build Warnings

Current build has ~28 warnings (mostly cross-reference anchors). These are cosmetic and don’t affect functionality.

To reduce warnings:

  • Fix internal cross-references in markdown files

  • Add explicit anchor targets with (anchor-name)= syntax

Documentation Not Updating

If changes aren’t appearing:

  1. Check ReadTheDocs build status

  2. Clear browser cache

  3. Trigger manual rebuild in ReadTheDocs dashboard

Version Management

ReadTheDocs automatically builds:

  • Latest: Development version from main branch

  • Stable: Latest tagged release

  • Version-specific: Each tag creates a versioned build

Example URLs:

  • Latest: https://kicad-sch-api.readthedocs.io/en/latest/

  • Stable: https://kicad-sch-api.readthedocs.io/en/stable/

  • v0.4.0: https://kicad-sch-api.readthedocs.io/en/v0.4.0/

Maintenance

Updating Sphinx Configuration

Edit docs/conf.py to change:

  • Theme settings

  • Extension configuration

  • Project metadata

Updating ReadTheDocs Configuration

Edit .readthedocs.yaml to change:

  • Python version

  • Build commands

  • Output formats

Monitoring Build Status

Add ReadTheDocs badge to README.md:

[![Documentation Status](https://readthedocs.org/projects/kicad-sch-api/badge/?version=latest)](https://kicad-sch-api.readthedocs.io/en/latest/?badge=latest)

Resources

Status: βœ… Fully configured and ready for ReadTheDocs deployment Next Step: Import project on ReadTheDocs.org