munchboka-edutools
Reusable Sphinx / Jupyter Book directives and assets for Norwegian educational content.
NEW: Includes muncho - a command-line tool for building beautiful, print-ready books with enhanced typography, layout, and automatic LaTeX math rendering for PDFs. See CLI_README.md for details.
Key Features
✨ Auto-configured Sphinx extensions for Jupyter Book
📚 Custom educational directives (quiz, dialogue, plots, animations, etc.)
🖨️ Print-optimized PDF builds with proper typography
🧮 Automatic PDF math rendering - LaTeX expressions work seamlessly in PDFs
🎨 Multiple build profiles (print, web, custom)
🎬 Animated plots - Create animations with transparent backgrounds (WebP/GIF)
📄 Print-friendly CSS - Browser "Print to PDF" creates clean problem sheets with answer keys
Install
pip install munchboka-edutools
Optional (nicer progress bars during slow builds, e.g. interactive-graph frame generation):
pip install munchboka-edutools[progress]
Usage
As Sphinx Extensions (Jupyter Book _config.yml)
sphinx:
extra_extensions:
- munchboka_edutools
All packaged directives are auto-registered. Static assets (including print-friendly CSS and JS) are placed under _static/munchboka/ during the build.
The core styles and scripts for part, answer, solution, goals, proof,
and hint automatically retry failed downloads twice, after 300 ms and 600 ms.
Retries preserve stylesheet order and use a fresh query parameter to bypass a
cached failure. This lets transient failures recover without a page refresh.
Rebuild and redeploy your book after upgrading to include the recovery handlers
in its HTML. Persistent network failures still require connectivity to return.
Interactive 3D math graphs
backend: threejs is the default for interactive-plot3d, giving live
rotation, zoom, and sliders with local renderer assets and a static print
fallback. The legacy frames backend is still available via an explicit
backend: frames. See the
Three.js guide for examples and migration limits.
Norwegian notebooks with Pyodide
Build a standalone JupyterLite site, or use the {notebook} directive to open
.ipynb exercises from a book. Students run Python in their browser and download
their work as standard Jupyter notebooks.
pip install "munchboka-edutools[notebook]"
muncho notebook build --output _build/notebook
python -m http.server 8000 --directory _build/notebook
The default site includes three Norwegian examples. See the notebook guide for Sphinx integration, custom exercises, browser storage, and package limitations.
Print-Friendly PDFs
Simply press Ctrl+P (or Cmd+P) in your browser when viewing any page to create a clean PDF with:
- All tabs flattened with part labels (a, b, c, etc.)
- Answers and solutions hidden from main content
- Automatic answer key page at the end
- CAS popup buttons hidden
- Better page breaks
See docs/print_pdf.md for details.
As Build Tool
Build books with enhanced formatting:
# Print-optimized build (includes automatic PDF math rendering)
muncho build matematikk_1t --profile print
# Web-optimized build
muncho build matematikk_r1 --profile web
# See all options
muncho --help
PDF Math Rendering: When building PDFs, muncho automatically configures sphinx.ext.imgmath to render LaTeX math expressions as high-quality SVG images. No changes to your source files needed!
See CLI_README.md for full CLI documentation and QUICKSTART.md for a quick start guide.
Development
Clone and install dev extras:
pip install -e .[dev]
Local demo book
Build the embedded demo book:
jupyter-book build book/
Adding a new directive
- Create
src/munchboka_edutools/directives/my_directive.pyexposingsetup(app). - The package auto-loads modules under
munchboka_edutools.directives. - Add an example page in
book/examples/.
Testing
Run tests:
pytest -q
To exercise asset recovery in a browser (requires Node.js and Playwright):
pytest tests/test_asset_recovery.py --basetemp=/tmp/munchboka-asset-tests
node tests/asset_recovery_browser.cjs /tmp/munchboka-asset-tests/test_core_asset_recovery0/out
Set MUNCH_CHROMIUM to a Chrome executable if Playwright's Chromium is not installed.
Quick Links
- Animation Quickstart - Create animated plots
- CLI Documentation - Build tool guide
- Quick Start - Get started quickly
- Print PDF Guide - Browser printing features
- Examples - See all directive examples
Releasing
Tag a version (v0.1.0) and the GitHub Action will build and publish.
License
MIT
1 maintainer
Metadata
1 maintainer
Release files for munchboka-edutools 0.10.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| munchboka_edutools-0.10.4.tar.gz | 43.9 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| munchboka_edutools-0.10.4-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 47.4 MB
Release files / munchboka_edutools-0.10.4.tar.gz
| Download URL | munchboka_edutools-0.10.4.tar.gz |
|---|---|
| Size | 43.9 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0bc8840aaca10b945451ef80cb53c5812981d09f7a55f121a7c9ccb15ea52d7d
|
|
BLAKE2b-256 checksum How to use checksums |
7881b1e4a210d7991a522258f781071a085c7ce6de4465fc23f740d7fed8be3c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.8
|
Release files / munchboka_edutools-0.10.4-py3-none-any.whl
| Download URL | munchboka_edutools-0.10.4-py3-none-any.whl |
|---|---|
| Size | 3.5 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e3c21042f47d43749aba8bac5d1a66db79411b2ea029695c39eb91d675655771
|
|
BLAKE2b-256 checksum How to use checksums |
126db7c2399a5acd9ed80bbe72cf25a432480fc04cd715631f256fc077b73cbd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.8
|
