Metadata-Version: 2.4
Name: sphinx-yaq
Version: 0.1.0
Summary: Interactive self-assessment quizzes for Sphinx HTML documentation
Author: Benjamin Perret
License-Expression: MIT
Project-URL: Documentation, https://github.com/PerretB/sphinx-yaq
Project-URL: Source, https://github.com/PerretB/sphinx-yaq
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Sphinx :: Extension
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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
Requires-Python: <3.15,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Sphinx<10,>=7; python_version < "3.14"
Requires-Dist: Sphinx<10,>=8.2; python_version >= "3.14"
Dynamic: license-file

# sphinx-yaq

Interactive self-assessment quizzes and hidden hints for Sphinx HTML documentation.
Write exercises in reStructuredText and let readers check their understanding
directly on the page.

## Features

- **True/false, fill-in-the-blank, and single-choice questions**, mixed freely
  within an exercise.
- **Flexible answer matching:** exact text and decimal numbers, fuzzy spelling,
  ordered or unordered sequences, regular expressions, and numerical comparison
  of mathematical expressions.
- **Immediate feedback, solution reveal, and restart** to support self-paced
  learning.
- **Inline and block spoilers** for hints, explanations, and worked solutions.
- **Automatic local progress** that survives page reloads in the same browser.
- **Keyboard-accessible controls** with accessible names and status announcements.
- **Static-site friendly:** packaged JavaScript and CSS, with no application
  server, account, cookie, or external service required by the extension.

YAQ is intended for self-assessment. Correct answers are included in generated
HTML and can be inspected by readers. Mathematical matching uses sampled
numerical evaluation, not symbolic proof.

## Installation

Supports Python 3.10–3.14 and Sphinx 7–9, subject to Sphinx's Python requirements.
Python 3.14 requires Sphinx 8.2 or newer. HTML builders only.

```console
python -m pip install sphinx-yaq
```

The first release is in preparation. To use a source checkout, run
`python -m pip install -e .` from the repository root.

Add the extension to your Sphinx `conf.py`:

```python
extensions = ["sphinx_yaq"]
```

## A first exercise

```rst
.. quiz:: first-quiz
   :title: A quick check

   Two plus two equals :quiz:`{"type":"FB","answer":"4","size":3}`.

   Four is an even number: :quiz:`{"type":"TF","answer":"T"}`.

   Choose an even number: :quiz:`{"type":"SC","values":"3,4,5","answer":"4"}`.

   .. spoiler:: Hint

      An even number is divisible by two.
```

Each quiz needs a page-unique identifier and a title. The extension adds its
browser assets automatically when Sphinx builds the HTML pages.

## Documentation

The [English user guide](docs/index.rst) includes
[installation instructions](docs/getting-started.rst),
[working examples](docs/examples.rst), the [authoring reference](docs/authoring.rst),
and [progress and privacy details](docs/progress.rst).

Build the documentation locally:

```console
python -m pip install -e . -r docs/requirements.txt
python -m sphinx -W --keep-going -E -b html docs docs/_build/html
python -m http.server 8000 --directory docs/_build/html
```

Open [localhost:8000](http://localhost:8000). The repository also includes
[Read the Docs configuration](.readthedocs.yaml) for publishing the HTML guide.

## Development

```console
python -m pip install -r requirements-test.txt
npm ci
npm run test:js
python -m pytest
python -m build
python scripts/smoke_test_wheel.py
```

Edit browser code in `frontend/src/` and regenerate the packaged bundle with
`npm run build:js`. See the [development guide](docs/contributing.rst).

## License

[MIT](LICENSE).
