Ansys Sphinx Theme

1.7.2 verified Fri May 01 auth: no python

A Sphinx theme devised by ANSYS, Inc. for documenting PyAnsys libraries and other projects. Version 1.7.2 requires Python >=3.10,<4. The theme provides a modern, responsive design with PyAnsys branding, including custom components like a version switcher, search, and navigation. It follows a monthly release cadence.

pip install ansys-sphinx-theme

Common errors

error ModuleNotFoundError: No module named 'ansys_sphinx_theme' ↓

cause The package is not installed or installed in a different environment.

fix

Run pip install ansys-sphinx-theme and ensure the correct Python environment is active.

error Theme 'ansys_sphinx_theme' is not registered ↓

cause The extension is not added to the extensions list in conf.py.

fix

Add 'ansys_sphinx_theme' to the extensions list in your conf.py.

error Sphinx version incompatibility: ansys-sphinx-theme requires sphinx>=4.0 ↓

cause Older versions of Sphinx are not supported.

fix

Upgrade Sphinx: pip install -U sphinx

Warnings

breaking Version 1.7.0 introduced dependency groups and may require updating your pyproject.toml or requirements if you relied on old optional extras. ↓

fix Check the new dependency groups in the repository's pyproject.toml and adjust your project dependencies accordingly.

deprecated Support for Python 3.9 is dropped starting from version 1.7.0. Use Python >=3.10. ↓

fix Update Python to 3.10 or later.

gotcha The theme expects a specific folder structure for static files; custom CSS/JS may be overwritten during theme updates. Always use custom CSS with the `html_static_path` setting. ↓

fix Place custom files in `_static` and reference them via `html_css_files` or `html_js_files` in conf.py.

Imports

ansys_sphinx_theme
```
import ansys_sphinx_theme
```

Quickstart

Basic setup in Sphinx conf.py to use the theme.

import ansys_sphinx_theme

# conf.py
extensions = [
    'ansys_sphinx_theme',
]
html_theme = 'ansys_sphinx_theme'
html_theme_options = {
    'github_url': 'https://github.com/ansys/ansys-sphinx-theme',
}