docs: fix Linux deps and improve contribution setup instructions

[its-me-maady]

• Remove Pillow build-from-source packages across macOS, Linux, and Alpine — they're bundled in the pre-built wheels
• Add missing libcairo to all platform install blocks (was listed in dependencies but not in the install commands)
• Describe each system dependency by which feature requires it
• Rewrite contribution setup to use hatch shell (consistent with other openZIM repos like ted, warc2zim, youtube)
• Clarify all commands must be run from the local clone root

Closes #152, Closes #153

[benoit74]

@its-me-maady I want this PR to fix once (and hopefully for all) the list of dependencies.

With your changes, we still have inconsistent things between the list and instructions for macOS, Linux and Alpine.

We need to ensure this is well understood, documented, or fixed.

I also feel like explaining how to install Pillow is beyond the scope of what we can reasonably maintain, so I would prefer we simply consider most users will do the basic install, and then redirect anyone needing to build from source to go to Pillow documentation.

I also like the way Pillow describe which optional dependencies are required for some features: Optionally, install [defusedxml](https://pypi.org/project/defusedxml/) for Pillow to read XMP data, and [olefile](https://pypi.org/project/olefile/) for Pillow to read FPX and MIC images. I think we should strive to have the same kind of wording since dependencies are needed only for few scraperlib features (e.g. wget is used only in few functions).

[its-me-maady]

Updated — removed all Pillow build-from-source packages across macOS, Linux, and Alpine, described each dependency by feature (wget, FFmpeg, gifsicle, libcairo), linked to Pillow docs for anyone needing to build from source, fixed the duplicate Linux header.

[benoit74]

Few questions/remarks:

• I don't think it is correct to say the dependencies are install by PyPI, they are rather install by pip (and from PyPi by default, but this depends on local pip configuration which might use a local mirror, or whatever else)
• do we really need to install libmagic, isn't this installed by python-magic?
• we should probably make it clearer that all dependencies are obviously needed to have all tests pass
• how did you tested you can drop all dependencies you've removed? For instance I'm a bit worried about the fact you remove libjpeg, pretty sure the "Alpine" case has been added by someone who tried to build/test the lib on Alpine and faced a problem. But problem/dependency might be gone, hence my question about how did you tested, because it is highly possible we just don't know it is not needed anymore

[its-me-maady]

Honestly, I didn't test it — the reasoning was that Pillow's pre-built wheels on macOS and Linux bundle their own image libraries, so those build deps shouldn't be needed at runtime. But I have no actual proof of this on a clean machine.
Alpine is a different story though — musl libc means manylinux wheels don't apply and Pillow likely builds from source there, so dropping libjpeg was wrong. I'm restoring it as libjpeg-turbo (which is what libjpeg wraps anyway, so either works — just being more explicit).
For macOS and Linux I'm not sure what the right call is — revert to be safe, or actually test on a clean environment? Happy to do either, just let me know.

[benoit74]

We cannot just throw changes just hopping they are right. This is the exact reason we've not made any change, because it is hard to check changes are correct so that we

We hence need (you or someone else) to test all these changes (in a realistic fashion, e.g. we won't test all Linux distro, a "standard" one like Debian or Ubuntu is ok) to confirm what needs to be installed manually and what is automatically installed by pip.

[its-me-maady]

Tested everything properly this time with Docker on both python:3.14-slim and python:3.14-alpine — ran the full test suite on both, 1057 passed, 69 skipped. The only failure is test_validate_folder_writable_not_writable which is a pre-existing issue with running as root in Docker (root can write anywhere so the "not writable" condition never triggers) — unrelated to these changes.

Commands used:

Debian:

docker run --rm -v $(pwd):/app -w /app python:3.14-slim sh -c "
apt-get update -q && apt-get install -y -q libmagic1 wget ffmpeg gifsicle libcairo2 bash
pip install '.[dev]' -q --root-user-action=ignore
invoke coverage"

Alpine:

docker run --rm -v $(pwd):/app -w /app python:3.14-alpine sh -c "
apk add -q ffmpeg gifsicle libmagic wget cairo bash
pip install '.[dev]' -q --root-user-action=ignore
invoke coverage"

Also noticed libcairo was missing from all three install blocks even though it's in the dependencies list — added it. On Alpine, Pillow's wheel already bundles libjpeg_turbo, libtiff, webp etc. so those removals are fine.

Only thing I couldn't test is macOS since I don't have a Mac, but brew install cairo is what everyone uses for the same cairocffi error so I'm fairly confident that's right.

[benoit74]

Thanks a lot, well done.

I'm ok with your approach regarding MacOS (I do have a Mac, but with so many things already installed that I can't trust any test ^^).

Few final refinements needed and we can merge. Please also edit first issue comment just like the changelog.

[its-me-maady]

Updated — changed "packages" to "dependencies" in the note, and updated the changelog entry to reflect what the PR actually does now.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.52%. Comparing base (8c16fa6) to head (db93e11).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #291   +/-   ##
=======================================
  Coverage   99.52%   99.52%           
=======================================
  Files          41       41           
  Lines        2516     2516           
  Branches      354      354           
=======================================
  Hits         2504     2504           
  Misses          8        8           
  Partials        4        4           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[benoit74]

LGTM, thank you!