Metadata-Version: 2.4
Name: sphinx-lightbox
Version: 0.5.0
Summary: Click-to-enlarge images for Sphinx documentation
Author-email: Aputsiak Niels Janussen <aputtu+sphinx@gmail.com>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/aputtu/sphinx-lightbox
Project-URL: Documentation, https://aputtu.github.io/sphinx-lightbox/
Project-URL: Repository, https://github.com/aputtu/sphinx-lightbox.git
Project-URL: Issues, https://github.com/aputtu/sphinx-lightbox/issues
Keywords: sphinx,extension,lightbox,images,documentation,accessibility
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Sphinx :: Extension
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Documentation :: Sphinx
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Sphinx<10.0,>=7.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-sphinx==0.6.3; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pytest-mock>=3.0; extra == "dev"
Requires-Dist: beautifulsoup4>=4.11.0; extra == "dev"
Requires-Dist: coverage[toml]>=7.0; extra == "dev"
Requires-Dist: tox>=4.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: types-docutils; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Requires-Dist: pip-audit>=2.7; extra == "dev"
Provides-Extra: docs
Requires-Dist: Sphinx<10.0,>=7.0; extra == "docs"
Requires-Dist: sphinx-autobuild>=2021.3.14; extra == "docs"
Dynamic: license-file

# sphinx-lightbox

`sphinx-lightbox` is a Sphinx extension that turns standard `.. image::`
and `.. figure::` directives into click-to-enlarge images in HTML output.
It uses a CSS checkbox-toggle mechanism, progressively enhanced with a small
JavaScript file for keyboard activation, focus management, Escape-to-close,
and optional gallery navigation.

Documentation is published at <https://aputtu.github.io/sphinx-lightbox/>.

## Quick Start

```bash
pip install sphinx-lightbox
```

Enable the extension in `conf.py`:

```python
extensions = ["lightbox"]
```

Opt a standard image into lightbox behavior:

```rst
.. image:: /images/example.png
   :alt: Example image.
   :class: lightbox
```

Figures are transformed by default and keep their normal page caption:

```rst
.. figure:: /images/example.png
   :alt: Example figure.

   This caption is also shown in the lightbox overlay.
```

## Development

Create a local virtual environment and install development dependencies:

```bash
make setup
```

Common commands:

| Command | Description |
| --- | --- |
| `make test` | Run the pytest suite |
| `make lint` | Run `ruff check` and `ruff format --check` |
| `make type` | Run `mypy` |
| `make check` | Run lint, type checks, and tests |
| `make docs` | Build PDF docs, HTML docs, and validate generated HTML |
| `make build` | Build distributions, run `twine check`, and validate archive contents |
| `make all` | Run check, docs, build, and dependency audit |

The documentation build writes HTML to `docs/_build/html/` and copies the PDF
download into `docs/_downloads/sphinx-lightbox.pdf` before rebuilding HTML, the
same pattern used by the GitHub Pages deployment workflow.

## Project Layout

```text
sphinx-lightbox/
|-- lightbox/                 Extension package
|   |-- lightbox.py
|   |-- py.typed
|   `-- static/
|       |-- lightbox.css
|       `-- lightbox.js
|-- docs/                     Sphinx documentation source
|   |-- _ext/                 Docs-only validation fixes
|   |-- _templates/           Accessible theme template overrides
|   |-- _downloads/           Generated PDF download location
|   `-- images/               Example images
|-- requirements/             Base, development, and docs requirements
|-- scripts/                  Local development and validation helpers
|-- tests/                    Unit and integration tests
|-- pyproject.toml
|-- tox.ini
`-- Makefile
```

## Requirements

- Python 3.10 or later
- Sphinx 7.0 through 9.x
- LaTeX tooling such as `latexmk` and `texlive-latex-extra` for PDF docs

## License

GPL-3.0-or-later.
