Pin Python version (or update Sphinx)

[mrienstra]

Python 3.13 breaks sphinx.builders.epub3, due to the removal of imghdr, see sphinx-doc/sphinx#10440

This can be resolved by upgrading to Sphinx v6.2.0 or newer (latest version is 8.2.3). This project currently uses sphinx 4.5.0.

Aside: myst-parser 0.18.1 won't work with sphinx 6+, latest version is 4.0.1. Probably many other dependencies would also need to be bumped. The current default theme (sphinx_rtd_theme) would probably need to jump from 1.3.0 to a newer release, latest is 3.0.2.

---

pyproject.toml:

[tool.poetry.dependencies]
python = "^3.8"

.readthedocs.yml:

  tools:
    python: "3.11"

... so obvious simple fix would be to set both of these to the same specific version, 3.11 or 3.12.

[TimeToBuildBob]

Good catch on the Python 3.13 incompatibility with Sphinx 4.x. The fix isn't trivial due to cascading dependency upgrades:

• `sphinx` 4.x → 6.2+ (minimum for Python 3.13 compatibility)
• `myst-parser` 0.18.x → 2.0+ (required for Sphinx 6+)
• `sphinx_rtd_theme` 1.3.x → 2.0+ (required for Sphinx 6+)
• `m2r2` may need replacement — it's largely unmaintained and conflicts with newer Sphinx
• `recommonmark` is deprecated in favor of `myst-parser`

The simplest path forward:

1. Pin `python = "^3.11"` in pyproject.toml (matching .readthedocs.yaml)
2. Bump `sphinx = "^7.0"`
3. Replace `m2r2` + `recommonmark` with `myst-parser` (handles all Markdown needs)
4. Bump `sphinx_rtd_theme`, `sphinx-tabs`, `sphinx-click` to latest

This would also be a good opportunity to modernize from poetry to a simpler pyproject.toml-based setup.

[ErikBjare]

@TimeToBuildBob Do it, I think we can skip all the way to Python 3.13 for docs (I'm planning to move all/many ActivityWatch packages/modules to 3.13 soon), but if there are blockers, I guess 3.11 is fine.

[TimeToBuildBob]

Done — PR #167 implements the full Sphinx upgrade:

• Sphinx 4.x → 9.0.4 (fixes Python 3.13 imghdr incompatibility)
• Drops m2r2 + recommonmark (replaced by myst-parser 5.0.0)
• Python constraint bumped to ^3.11
• CI and ReadTheDocs updated to Python 3.13

[TimeToBuildBob]

Done! PR #167 now has CI green with Python 3.13.

Changes in the PR:

• Sphinx 7+ (pinned <9) — Sphinx 9 has a known incompatibility with sphinx-tabs (sphinx-tabs is not compatible with Sphinx 9 executablebooks/sphinx-tabs#209), so we use Sphinx 8.2.3 which fully supports Python 3.13
• myst-parser replaces the unmaintained m2r2 + recommonmark
• Python 3.13 in both .readthedocs.yml and CI
• extlinks captions updated for Sphinx 7+ format (%s required)
• language = "en" instead of deprecated None
• Excluded duplicate changelog .md files from build (.rst versions are the ones included by changelog.rst)

Ready for review/merge.

[ErikBjare]

Fixed in #167 just merged