diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index e63b139b..e6184607 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -87,20 +87,20 @@ jobs: fail-fast: false matrix: os: [ubuntu-latest, windows-latest, macos-latest] - python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "pypy3.9"] + python-version: ["3.10", "3.11", "3.12", "3.13", "3.14", "pypy3.10"] include: - os: ubuntu-latest python-version: "3.10" with-coverage: true - os: ubuntu-latest - python-version: 3.13 + python-version: 3.14 tox-env: devel - os: windows-latest - python-version: 3.13 + python-version: 3.14 tox-env: devel - os: macos-latest - python-version: 3.13 + python-version: 3.14 tox-env: devel steps: @@ -163,11 +163,11 @@ jobs: strategy: fail-fast: false matrix: - python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "pypy3.9"] + python-version: ["3.10", "3.11", "3.12", "3.13", "3.14", "pypy3.10"] include: - python-version: "3.10" with-coverage: true - - python-version: 3.13 + - python-version: 3.14 tox-env: devel steps: @@ -233,9 +233,9 @@ jobs: strategy: fail-fast: false matrix: - python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "pypy3.9"] + python-version: ["3.10", "3.11", "3.12", "3.13", "3.14", "pypy3.10"] include: - - python-version: 3.13 + - python-version: 3.14 tox-env: devel steps: diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index ec69769c..30d58ea2 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -48,7 +48,7 @@ repos: rev: v3.21.2 hooks: - id: pyupgrade - args: [--py39-plus] + args: [--py310-plus] - repo: https://github.com/pre-commit/mirrors-eslint rev: v10.0.0-beta.0 diff --git a/docs/user_guide.rst b/docs/user_guide.rst index 8415bfb0..4862606e 100644 --- a/docs/user_guide.rst +++ b/docs/user_guide.rst @@ -51,10 +51,117 @@ The plugin will issue a warning when adding files or links to the standalone rep Enhancing reports ----------------- +Themes +~~~~~~ + +pytest-html supports pluggable themes via Jinja2 template inheritance. Two +built-in themes are included: **classic** (the default, preserving the +traditional appearance) and **modern** (a card-based dashboard style). + +Selecting a theme +^^^^^^^^^^^^^^^^^ + +Set the ``html_theme`` option in your pytest configuration: + +Using ``pyproject.toml``: + +.. code-block:: toml + + [tool.pytest.ini_options] + html_theme = "modern" + +Using ``pytest.ini``: + +.. code-block:: ini + + [pytest] + html_theme = modern + +Using a local theme directory +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You can point to a custom theme directory using ``html_theme_path``. This +overrides entry point-based theme discovery and does not require packaging: + +.. code-block:: toml + + [tool.pytest.ini_options] + html_theme_path = "./my_theme" + +The theme directory must contain at least a ``layout.jinja2`` file that extends +the base template: + +.. code-block:: jinja + + {% extends "base.jinja2" %} + + {% block header %} +
Custom header content here
+ {% endblock header %} + +Optionally include a ``style.css`` to replace the default stylesheet entirely. +If no ``style.css`` is present, the classic theme's CSS is used as a fallback. + +The ``--css`` flag continues to work and appends additional CSS on top of +whatever the theme provides. + +Creating a theme package +^^^^^^^^^^^^^^^^^^^^^^^^ + +Theme packages register via the ``pytest_html.themes`` entry point group. The +entry point value must be a Python package (directory with ``__init__.py``) +containing the theme resources. + +Example package structure: + +.. code-block:: text + + pytest-html-dark/ + src/ + pytest_html_dark/ + __init__.py + theme/ + __init__.py + layout.jinja2 + style.css + pyproject.toml + +Register the entry point in ``pyproject.toml``: + +.. code-block:: toml + + [project.entry-points."pytest_html.themes"] + dark = "pytest_html_dark.theme" + +Users can then select the theme: + +.. code-block:: toml + + [tool.pytest.ini_options] + html_theme = "dark" + +Available template blocks +^^^^^^^^^^^^^^^^^^^^^^^^^ + +The base template (``base.jinja2``) provides the following overridable blocks: + +- ``styles`` -- CSS delivery (inline ``