Developer Experience Requirements¶
This document defines the developer experience (DX) requirements for the sphinx-autodoc-toml project. These requirements ensure that contributors have a smooth, efficient, and enjoyable development workflow.
Overview¶
Developer experience is a first-class concern for this project. We aim to minimize friction, maximize productivity, and provide clear feedback at every step of the development process.
Core Principles¶
Fast Feedback Loops: Developers should get quick feedback from tests, linting, and builds
Simple Setup: Getting started should require minimal steps and be well-documented
Clear Communication: Tools should provide actionable error messages and suggestions
Consistent Workflows: All common tasks should follow predictable patterns
Dogfooding: We use our own tools to ensure they work well
Project Structure¶
The src-layout (with code in src/sphinx_autodoc_toml/) provides clear separation between source code and development files, preventing accidental imports of development code during testing.
Environment Setup¶
The project provides clear setup instructions that require only two tools (uv and hatch) to get started. The specification Package installation MUST u... (S_BUILD_002) implements this by using uv for package installation.
Developers should be able to set up their development environment, including pre-commit hooks, with a single command (hatch run setup). This reduces friction and ensures all developers have a consistent environment configured correctly from the start.
Requirement: Dependency installation SHOULD complete in under 10 seconds on average hardware. R_DX_002
|
By using uv as the package installer (see Package installation MUST u... (S_BUILD_002)), we achieve significantly faster dependency resolution and installation compared to traditional pip-based workflows.
Testing Workflow¶
The specification Test commands MUST provide ... (S_DX_001) ensures test commands provide clear, actionable output.
Quick test execution enables rapid iteration and test-driven development practices.
Developers can view coverage inline during development (hatch run test:run) or generate detailed HTML reports for deeper analysis (hatch run test:cov).
Code Quality & Linting¶
Pre-commit hooks provide immediate feedback before code is committed, catching issues locally that would otherwise fail in CI. The hooks use the same hatch commands as CI to ensure consistency between local development and continuous integration.
Currently, linting steps run sequentially via Linting MUST be runnable vi... (S_LINT_002). Future optimization could run ruff and mypy in parallel to reduce feedback time.
We use ruff for linting, which provides clear, actionable error messages with explanations and often suggests specific fixes.
Requirement: Developers SHOULD be able to auto-fix most linting issues with a single command. R_DX_007
|
The hatch run lint:format command (implementing Code formatting MUST be aut... (S_DX_002)) automatically fixes formatting issues, reducing manual work.
Documentation¶
This ensures documentation stays accurate and complete as the project evolves. When implemented, this will enhance Documentation MUST be build... (S_DOCS_001).
Fast documentation builds enable developers to quickly verify their documentation changes.
Build Performance¶
Using uv_build as the build backend (The build backend SHOULD us... (S_BUILD_003)) provides 10-35x faster builds compared to traditional build backends.
Requirement: Build errors MUST clearly indicate which file or configuration is problematic. R_DX_011
|
Clear error messages help developers quickly identify and fix issues. The build backend (The build backend MUST be P... (S_BUILD_001)) provides excellent error reporting.
Packaging¶
Requirement: Source distributions MUST include all files needed to run tests and build docs. R_DX_012
|
This ensures that anyone who downloads the source distribution can fully develop and test the package. The specification Build configuration MUST in... (S_BUILD_004) implements this requirement.
Reproducible builds ensure that the same source code produces identical results across different machines and time periods. We use uv.lock (generated by uv lock) to lock all dependencies to specific versions. The specification Dependencies MUST be locked... (S_BUILD_005) implements dependency locking.
Common Development Commands¶
All development tasks are accessible through simple, memorable commands:
# Initial Setup (one-time)
hatch run setup # Install pre-commit hooks
# Pre-commit Hooks (runs automatically before commits)
pre-commit run --all-files # Run all hooks manually
pre-commit install # Re-install hooks if needed
# Testing
hatch run test:run # Run tests with coverage
hatch run test:cov # Generate HTML coverage report
# Linting
hatch run lint:all # Run all linting checks
hatch run lint:check # Check code with ruff
hatch run lint:format # Auto-format code
hatch run lint:typing # Type check with mypy
# Documentation
hatch run docs:build # Build documentation
hatch run docs:clean # Clean documentation build
# Building
hatch build # Build package
# Dependency Management
uv lock # Update uv.lock file with latest compatible versions
uv sync # Sync environment with uv.lock
Metrics & Goals¶
Metric |
Target |
Current Status |
Requirement |
Specification |
|---|---|---|---|---|
Dependency install time |
< 10s |
✓ Implemented (~5s with uv) |
||
Test suite execution |
< 30s |
✓ Implemented (~2s) |
||
Package build time |
< 5s |
✓ Implemented (~3s with uv_build) |
||
Documentation build |
< 15s |
⚠ In progress |
||
Time to first contribution |
< 5 min |
✓ Implemented |
Summary of Requirements¶
Implemented Requirements¶
The following developer experience requirements are fully implemented:
Open Requirements¶
The following developer experience requirements are still in progress:
Supporting Specifications¶
These requirements are supported by the following specifications:
The build backend MUST be P... (S_BUILD_001): PEP 517 compliant build backend (pyproject.toml)
Package installation MUST u... (S_BUILD_002): Use uv for package installation (pyproject.toml)
The build backend SHOULD us... (S_BUILD_003): Use uv_build for optimal performance (pyproject.toml)
Build configuration MUST in... (S_BUILD_004): Include tests in source distribution (pyproject.toml)
Dependencies MUST be locked... (S_BUILD_005): Locked dependencies for reproducibility (pyproject.toml)
Test commands MUST provide ... (S_DX_001): Clear, actionable test output (pyproject.toml)
Code formatting MUST be aut... (S_DX_002): Automated code formatting (pyproject.toml)
Documentation MUST demonstr... (S_DX_003): Dogfooding autodoc-toml (pyproject.toml)
Package layout MUST follow ... (S_DX_004): Src-layout convention (this document)
S_DX_005: Pre-commit hooks use hatch commands (.pre-commit-config.yaml)
A single 'hatch run setup' ... (S_DX_006): Single setup command for dev environment (pyproject.toml)
Documentation MUST be build... (S_DOCS_001): Buildable via hatch command (pyproject.toml)
Linting MUST be runnable vi... (S_LINT_002): Linting via hatch command (pyproject.toml)
Package Publishing & Release¶
Automated publishing reduces the manual effort and potential errors in the release process. When a GitHub Release is published, the package should automatically be built, tested, and uploaded to PyPI.
Trusted Publishing (OIDC-based authentication) eliminates the need for long-lived API tokens, improving security. GitHub Actions authenticates directly with PyPI using short-lived tokens that cannot be extracted or reused.
Requirement: Development versions MUST be automatically published to TestPyPI on main branch pushes. R_DX_018
|
Automatically publishing development versions to TestPyPI allows contributors to test pre-release versions and verify their changes work correctly when installed as a package. This catches packaging issues early.
Requirement: Development version numbers MUST include commit count and hash for traceability. R_DX_019
|
Development versions use the format {base}.dev{count}+{hash} (e.g., 0.1.0.dev42+a1b2c3d) to enable tracing each published version back to its exact commit. This helps with debugging and verification.
All quality checks (tests, linting, type checking) must pass before a package is published to either PyPI or TestPyPI. This prevents broken or low-quality releases.
Requirement: Maintainers SHOULD be able to manually trigger publishing for emergency releases. R_DX_021
|
A manual workflow dispatch option allows maintainers to publish releases outside the normal automation (e.g., hotfixes, testing the workflow), with the choice of publishing to either PyPI or TestPyPI.
Complete documentation ensures that any maintainer can execute releases confidently. The RELEASING.md file documents the entire process, including setup of trusted publishing, creating releases, version numbering, and troubleshooting.
Requirement: Contributors SHOULD receive immediate feedback when their PR is published to TestPyPI. R_DX_023
|
When a pull request is merged to main and published to TestPyPI, the workflow should automatically comment on the associated PR with the version number and installation instructions. This enables rapid testing and validation.
Future Improvements¶
Implement parallel linting (All linting tools MUST run ... (R_DX_005))
Add
-Wflag to Sphinx builds to fail on warnings (Documentation builds MUST f... (R_DX_008))Optimize documentation build performance (Documentation SHOULD build ... (R_DX_009))
Consider watch mode for tests and documentation
Architecture¶
This demonstrates the ideal separation of concerns:
Requirements (this document): Define WHAT we need from a developer experience perspective
Specifications (pyproject.toml, .github/workflows/*.yml): Define HOW the system is technically implemented
Requirements focus on outcomes and user needs, while specifications describe the technical implementation details embedded in the configuration and workflow files themselves.
