Contributing¶

Thank you for your interest in contributing to sphinx-autodoc-toml! This guide covers everything you need to know to contribute effectively.

We welcome all types of contributions:

Bug reports and feature requests
Documentation improvements
Code contributions (bug fixes, new features, refactoring)
Test improvements
Requirements and specifications

Developer Experience Philosophy¶

This project treats developer experience as a first-class concern, similar to “platform as a product” thinking. We aim to:

Minimize friction and setup time
Provide fast feedback loops
Maintain clear documentation
Use consistent, predictable workflows
Dogfood our own tools

See Developer Experience Requirements for our complete DX requirements.

Getting Started¶

Prerequisites¶

You need two tools installed:

uv - Fast Python package manager
hatch - Task runner and environment manager

Installation¶

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install hatch
uv tool install hatch

Clone and Setup¶

# Clone the repository
git clone https://github.com/calvingiles/autodoc-toml.git
cd autodoc-toml

# Set up development environment (installs pre-commit hooks)
hatch run setup

That’s it! The hatch run setup command installs pre-commit hooks that automatically run quality checks before each commit.

Development Workflow¶

Making Changes¶

Create a branch for your changes:

git checkout -b feature/your-feature-name

Make your changes following our coding standards (see below)
Run tests to verify your changes:
```
hatch run test:run
```
Run linting to check code quality:
```
hatch run lint:all
```
Commit your changes (pre-commit hooks will run automatically):
```
git add .
git commit -m "Description of your changes"
```

Push and create a pull request:

git push origin feature/your-feature-name

Requirements Traceability¶

CRITICAL: This project maintains a complete traceability chain from requirements through specifications to tests. When making changes, you MUST keep this chain synchronized.

The Three-Level Chain¶

Requirements (R_*)  →  Specifications (S_*)  →  Tests (T_*)
    (WHAT)                  (HOW)                (VERIFY)

Requirements (R_*): Define WHAT the system needs to do
- Location: docs/requirements/*.md
- Example: R_PARSE_001 - “The system MUST parse TOML files”
Specifications (S_*): Define HOW requirements are implemented
- Location: Implementation docstrings, pyproject.toml doc-comments, workflow files
- Example: S_PARSER_005 - “The parser MUST use tomlkit”
- Links to: One or more requirements
Tests (T_*): VERIFY specifications are correct
- Location: Test docstrings
- Example: T_PARSER_001 - “Verify parser extracts doc-comments”
- Links to: One or more specifications

When Adding Features¶

First: Create requirement(s) in docs/requirements/
Second: Add specification(s) to implementation docstrings
Third: Add test(s) with sphinx-needs directives
Finally: Link them: Test :links: Spec, Spec :links: Requirement

Example:

# In docs/requirements/core-features.md
```{req} The parser MUST support inline tables.
:id: R_PARSE_008
:status: planned
:tags: parser, toml
:links: S_PARSER_011
```

# In src/sphinx_autodoc_toml/parser.py
"""
.. spec:: The parser MUST recognize TOML inline table syntax.
   :id: S_PARSER_011
   :status: implemented
   :tags: parser, toml
   :links: R_PARSE_008
"""

# In tests/test_parser.py
"""
.. test:: Verify parser handles inline tables correctly.
   :id: T_PARSER_010
   :status: implemented
   :tags: parser, toml
   :links: S_PARSER_011
"""

For complete guidelines, see CLAUDE.md in the repository root.

Common Development Tasks¶

Running Tests¶

# Run all tests with coverage
hatch run test:run

# Generate HTML coverage report
hatch run test:cov

# Open coverage report
open htmlcov/index.html  # macOS
xdg-open htmlcov/index.html  # Linux

Code Quality¶

# Run all quality checks (linting + formatting + type checking)
hatch run lint:all

# Individual checks
hatch run lint:check        # Ruff linting
hatch run lint:format-check # Check formatting
hatch run lint:typing       # MyPy type checking

# Auto-fix formatting issues
hatch run lint:format

Pre-commit Hooks¶

Pre-commit hooks run automatically before each commit. To run them manually:

# Run on all files
pre-commit run --all-files

# Run on staged files only
pre-commit run

Documentation¶

# Build documentation
hatch run docs:build

# Clean build artifacts
hatch run docs:clean

# View documentation
open docs/_build/html/index.html  # macOS
xdg-open docs/_build/html/index.html  # Linux

Building Packages¶

# Build wheel and source distribution
hatch build

# Output will be in dist/

Dependency Management¶

Dependencies are locked in uv.lock for reproducible builds:

# Update lock file with latest compatible versions
uv lock

# Sync environment with lock file
uv sync

The lock file is committed to version control to ensure consistency.

Code Standards¶

Style Guidelines¶

Line length: Maximum 100 characters
Formatting: Use ruff format (runs automatically via pre-commit)
Linting: Follow ruff rules (E, F, I, N, W, UP)
Type hints: All functions must have type annotations
Docstrings: All public functions/classes must have docstrings

Testing Guidelines¶

Keep tests focused on a single behavior
Use descriptive test names
Include sphinx-needs .. test:: directives
Add Implements: T_XXX_YYY comments
Test both success and failure cases
Aim for >80% code coverage

Documentation Standards¶

All public APIs must be documented
Complex logic should have inline comments explaining “why”
Update sphinx-needs specs when implementation changes
Use the autodoc-toml directive to document pyproject.toml

Submitting Pull Requests¶

Before Submitting¶

Ensure all tests pass: hatch run test:run
Ensure linting passes: hatch run lint:all
Update documentation if needed
Add requirements/specs/tests following the traceability chain
Write a clear PR description explaining your changes

PR Review Process¶

GitHub Actions will run all CI checks
Maintainers will review your code
Address any feedback or requested changes
Once approved, your PR will be merged

After Merge¶

When your PR is merged to main:

A development version is automatically published to TestPyPI
The workflow will comment on your PR with installation instructions
You can test your changes: pip install --index-url https://test.pypi.org/simple/ sphinx-autodoc-toml

Release Process¶

For maintainers: see RELEASING.md for complete instructions on:

Configuring PyPI Trusted Publishing
Creating stable releases
Publishing to PyPI
Version numbering guidelines

Development versions are published automatically to TestPyPI on every push to main.

Getting Help¶

Questions: Open a GitHub Discussion
Bug Reports: File an Issue
Documentation: Check the docs at https://calvingiles.github.io/autodoc-toml/

Code of Conduct¶

This project follows the standard open source code of conduct:

Be respectful and inclusive
Welcome newcomers
Focus on what’s best for the community
Show empathy toward others

Thank you for contributing!

sphinx-autodoc-toml

Navigation

Related Topics