Set up Sphinx Documentation Infrastructure

[posborne]

Overview

Set up Sphinx-based documentation infrastructure for the Fastly Compute Python SDK, enabling auto-generated API documentation from docstrings. This issue focuses on getting docs to generate consistently - hosting location and styling are out of scope.

Goals

1. Configure Sphinx with autodoc - Generate API docs from code
2. Standardize docstring format - Convert all docstrings to Sphinx RST style (:param:, :returns:, :raises:)
3. Build infrastructure - Add make docs and CI validation
4. Fix inconsistencies - Some modules use Google style (Args:), others use RST style

Out of Scope:

• Documentation hosting platform (Read the Docs, GitHub Pages, etc.)
• Documentation styling/theming
• Hosting deployment configuration

Current State

Inconsistent docstring formats:

• ✅ config_store.py, erl.py - Use Sphinx RST style (:param:, :raises:, Example::)
• ❌ requests/__init__.py - Uses Google style (Args:, Raises:, Note:)
• ❌ Test files - Mixed styles

RST format example (preferred):

def get(self, key: str, default: str | None = None) -> str | None:
    """Get a configuration value.

    :param key: The configuration key
    :param default: Default value if key not found
    :return: Configuration value or default if not found
    :raises ~fastly_compute.exceptions.types.error.InvalidArgument: If the key is invalid

    Example::

        config = ConfigStore.open("app-config")
        api_url = config.get("api_url", "https://api.example.com")
    """

Tasks

1. Sphinx Setup

   • Install Sphinx and autodoc extension
   • Create docs/ directory with conf.py, index.rst
   • Configure autodoc to generate API reference from fastly_compute/ modules
   • Add intersphinx for cross-references to Python stdlib

2. Standardize Docstrings

   • Convert requests/ module docstrings from Google style to RST style
   • Audit all other modules for consistency
   • Update any remaining Google-style docstrings to RST format
   • Use full exception paths in :raises: (e.g., ~fastly_compute.exceptions.types.error.InvalidArgument)

3. Build Process

   • Add make docs target to build HTML documentation
   • Configure Sphinx to fail on warnings (ensure all docstrings are valid RST)
   • Add CI check to validate docs build successfully

4. Documentation Standards Guide

   • Document the RST format convention in contributing guide
   • Provide examples for common patterns (module docstrings, class docstrings, method docstrings)
   • Reference config_store.py and erl.py as canonical examples

Acceptance Criteria

• Sphinx generates HTML documentation without warnings
• All modules use consistent RST docstring format
• make docs builds complete API reference
• CI validates documentation builds successfully
• Contributing guide documents RST format requirements

Cross-SDK Comparison: Rust uses rustdoc, Go uses godoc, JS uses JSDoc/TypeScript. Python ecosystem standard is Sphinx with RST docstrings, which integrates well with IDEs and type checkers.

Reference

• Sphinx Documentation
• Read the Docs
• Existing docstring examples in fastly_compute/config_store.py and fastly_compute/erl.py