sphinx-autoimage

sphinx-autoimage provides two Sphinx directives, autoimage and autofigure, for builder-aware image and figure scaling.

The extension keeps compatibility with the legacy :scale-<builder>: options, such as :scale-html: and :scale-latex:, but the preferred interface is now configuration-driven and open for custom builders.

The extension is based on autoimage for Sphinx by kroger

Usage

Enable the extension

Add the extension to your Sphinx conf.py:

extensions = [
    "sphinx_autoimage",
]

Configure image source directories

autoimage_sources defines where the extension searches for image files. Relative paths are resolved against the Sphinx source directory.

autoimage_sources = [
    ".",
    "_images",
    "../shared/images",
]

If an image is found in one of these directories, the extension rewrites the image URI so that Sphinx can process it from the current document. If no matching file is found, the original URI is kept unchanged.

Configure builder-specific default scaling

autoimage_scales maps Sphinx builder names or builder formats to percentage values.

autoimage_scales = {
    "html": 100,
    "singlehtml": 100,
    "latex": 70,
    "simplepdf": 70,
    "qthelp": 100,
    "epub2": 100,
    "mobi": 100,

    # Custom builders can be added without changing the extension code.
    "my-custom-builder": 85,

    # Optional fallback for builders without a more specific value.
    "*": 100,
}

The following legacy builder keys are part of the built-in base configuration and can be overridden in conf.py:

• html
• singlehtml
• latex
• simplepdf
• qthelp
• epub2
• mobi

Set a value to None to disable the default scale for a builder.

When no builder-specific entry matches, autoimage_scales["*"] is used as a generic fallback if it is configured. Using this fallback emits one warning per builder/format pair by default, because it usually means that a builder has not been configured explicitly.

Disable the warning when the fallback is intentional:

autoimage_warn_on_scale_fallback = False

Alternatively, add an explicit entry for the builder or builder format:

autoimage_scales = {
    "html": 100,
    "latex": 70,
    "my-custom-builder": 85,
    "*": 100,
}

The fallback warning is emitted as a Sphinx warning of type autoimage.scale-fallback.

Configure default alignment

By default, autoimage and autofigure center images when no explicit :align: option is provided.

autoimage_default_align = "center"

Set the value to an empty string to disable automatic alignment:

autoimage_default_align = ""

Use autoimage

Preferred syntax with open builder mapping:

.. autoimage:: diagrams/architecture.png
   :scale-for: html=100, latex=70, my-custom-builder=85
   :alt: Architecture overview

Configuration-only syntax:

.. autoimage:: diagrams/architecture.png
   :alt: Architecture overview

Legacy syntax remains supported:

.. autoimage:: diagrams/architecture.png
   :scale-html: 100
   :scale-latex: 70
   :alt: Architecture overview

Use autofigure

.. autofigure:: diagrams/architecture.png
   :scale-for: html=100, latex=70
   :alt: Architecture overview

   Architecture overview

autofigure supports the standard Sphinx figure options in addition to the autoimage scale options.

Scale precedence

For each image node created by autoimage or autofigure, the selected scale is resolved in this order:

1. :scale-for: for the current builder.name
2. legacy :scale-<builder>: for the current builder.name
3. :scale-for: for the current builder.format
4. standard directive option :scale:
5. autoimage_scales[builder.name]
6. autoimage_scales[builder.format]
7. autoimage_scales["*"] generic fallback, with a warning unless autoimage_warn_on_scale_fallback = False

Builder-specific scaling is applied during Sphinx's doctree-resolved event. This keeps the cached Sphinx environment builder-neutral and avoids requiring sphinx-build -E just because a different builder is used.

Build

This project uses uv and the uv_build backend.

Install development dependencies

uv sync --all-groups

Run checks

uv run ruff check src/sphinx_autoimage tests
uv run ruff format --check src/sphinx_autoimage tests
uv run pytest

Build source distribution and wheel

uv build

The generated artifacts are written to dist/:

dist/sphinx_autoimage-<version>.tar.gz
dist/sphinx_autoimage-<version>-py3-none-any.whl

Install locally for testing

Install the project into the current environment:

uv pip install -e .

Or install the generated wheel:

uv pip install dist/sphinx_autoimage-<version>-py3-none-any.whl

GitHub Actions

The repository includes two workflows:

• .github/workflows/ci.yaml runs linting, formatting checks, tests, and package builds.
• .github/workflows/release.yaml builds and publishes a GitHub release from a tag.