Documentation and Style

Use one Python convention from the first function. This project uses the Google Python Style Guide, Sphinx for generated API documentation, and pytest for unit tests.

The project contract

Use snake_case for functions and variables, PascalCase for classes, and four spaces for indentation. Give public functions and classes type annotations and a Google style docstring. Use Args:, Returns:, and Raises: when they apply.

def calculate_gc_content(sequence: str) -> float:
    """Calculates the GC fraction of a DNA sequence.

    Args:
        sequence: A nonempty DNA sequence containing A, C, G, and T.

    Returns:
        The fraction of bases that are G or C.

    Raises:
        ValueError: If the sequence is empty or contains another character.
    """
    normalized_sequence = sequence.upper()
    valid_bases = {"A", "C", "G", "T"}
    if not normalized_sequence or not set(normalized_sequence) <= valid_bases:
        raise ValueError("sequence must contain only A, C, G, and T")

    gc_count = normalized_sequence.count("G") + normalized_sequence.count("C")
    return gc_count / len(normalized_sequence)

The type hints let editors and type checkers inspect the API. The docstring explains meaning, units, assumptions, and errors that types cannot express. Test functions are an exception. A clear test_* name is enough when the test body is short.

Generate API documentation with Sphinx

Add the documentation tool as a development dependency in an existing uv project:

uv add --dev sphinx

Enable both autodoc and napoleon in docs/conf.py.

extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.napoleon",
]

autodoc_typehints = "description"

Napoleon reads Google style docstrings and passes them to Sphinx. Generate the API pages, then build the HTML documentation:

uv run sphinx-apidoc -f -o docs/source src/gene_tools
uv run sphinx-build -b html docs/source docs/build/html

Keep the docstring next to the code. Do not repeat function signatures by hand in a separate HTML page. Sphinx reads the module, its type hints, and its docstring from the same source that pytest runs.

Tests sit beside the package source

pytest is the unit testing standard for Python in this project. Add it to the project and point pytest at the tests/ directory.

uv add --dev pytest

[tool.pytest.ini_options]
testpaths = ["tests"]

gene_tools/
  src/
    gene_tools/
      sequence.py
  tests/
    test_sequence.py
  docs/
    conf.py
    source/
  pyproject.toml

import pytest

from gene_tools.sequence import calculate_gc_content


def test_calculate_gc_content_rejects_invalid_bases() -> None:
    with pytest.raises(ValueError, match="only A, C, G, and T"):
        calculate_gc_content("AUGC")

Run uv run pytest before a merge. The Testing and Assertions lesson covers numeric tolerances, known answers, invariants, edge cases, and random number generators.

Documentation checklist

Before merging a public Python function or class, check the following:

Check	Required action
Name	Use snake_case for functions and PascalCase for classes.
Types	Add parameter and return annotations.
Docstring	Use Google sections and describe behavior, units, and errors.
Imports	Import modules or packages. Keep standard aliases such as numpy as np.
Tests	Add a pytest test for the public behavior.
API reference	Build Sphinx with sphinx.ext.autodoc and sphinx.ext.napoleon.

Next steps

Read Testing and Assertions for the pytest suite that protects this documented API. The Sphinx Napoleon documentation explains each supported Google docstring section.