DC004: HasAPIReference

Overview

Property	Value
ID	DC004
Name	HasAPIReference
Group	documentation
Severity	NOTE

Description

Checks for API documentation generation setup.

API reference documentation provides:

Complete function/class signatures
Parameter descriptions
Return value documentation
Auto-generated from docstrings

What it checks

The check looks for API documentation configuration:

Sphinx conf.py with autodoc extension
MkDocs with mkdocstrings plugin
quartodoc configuration in _quarto.yml
pdoc configuration

Also checks for generated API docs in:

docs/api/
docs/reference/

How to fix

Option 1: quartodoc (recommended for Quarto)

Install quartodoc:

pip install quartodoc

Add to _quarto.yml:

quartodoc:
  package: my_package
  dir: reference
  sections:
    - title: API Reference
      contents:
        - my_package.core
        - my_package.utils

Option 2: Sphinx + autodoc

Add to docs/conf.py:

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

autodoc_default_options = {
    "members": True,
    "undoc-members": True,
    "show-inheritance": True,
}

Generate API docs:

sphinx-apidoc -o docs/api src/my_package

Option 3: MkDocs + mkdocstrings

Add to mkdocs.yml:

plugins:
  - mkdocstrings:
      handlers:
        python:
          options:
            docstring_style: google

Create docs/api.md:

# API Reference

::: my_package.core
::: my_package.utils

Option 4: pdoc

Install and run:

pip install pdoc
pdoc my_package -o docs/api

Write good docstrings

API docs are generated from docstrings. Use a consistent style:

def process(data: str, *, validate: bool = True) -> dict:
    """Process input data and return results.

    Parameters
    ----------
    data
        The input data to process.
    validate
        Whether to validate input. Defaults to True.

    Returns
    -------
    dict
        Processed results with 'status' and 'output' keys.

    Raises
    ------
    ValueError
        If data is empty or invalid.

    Examples
    --------
    >>> process("hello")
    {'status': 'ok', 'output': 'HELLO'}
    """

Why NOTE severity?

This check is a NOTE because:

Small packages may not need formal API docs
README documentation may be sufficient
Some projects prefer external documentation

Configuration

Skip this check

[tool.pycmdcheck]
skip = ["DC004"]

CLI

pycmdcheck --skip DC004