From 48d37cf12a764b0c835574c23e6d429a90afc31f Mon Sep 17 00:00:00 2001
From: Daniel Schadt <kingdread@gmx.de>
Date: Tue, 29 Jul 2025 22:48:25 +0200
Subject: add documentation for hittekaart_py

This is not 100% fietsboek, but it's closely related, and I don't think
setting up a separate site for hittekaart is worth it. At the moment,
this is a bit WIP, as the module sits in its own branch in the
hittekaart repository, but in the long run I want to use this. It also
is an experiment to see how well PyO3 works, as we potentially want to
migrate other parts of fietsboek to Rust in the future (no specifics
yet, but keeping the option available is nice).

In tox.ini, we disable -f for sphinx-apidoc, so that it doesn't
overwrite the modules.rst file. This means that the directory must be
clean if you re-generate the docs (it is on the CI server).

Also, we un-gitignore the modules.rst and hittekaart_py.rst files, as
special cases. The others are still auto-generated, so all good, but
these two we need.
---
 doc/developer/module/hittekaart_py.rst | 137 +++++++++++++++++++++++++++++++++
 doc/developer/module/modules.rst       |   8 ++
 2 files changed, 145 insertions(+)
 create mode 100644 doc/developer/module/hittekaart_py.rst
 create mode 100644 doc/developer/module/modules.rst

(limited to 'doc/developer')

diff --git a/doc/developer/module/hittekaart_py.rst b/doc/developer/module/hittekaart_py.rst
new file mode 100644
index 0000000..1df3e8c
--- /dev/null
+++ b/doc/developer/module/hittekaart_py.rst
@@ -0,0 +1,137 @@
+hittekaart_py package
+=====================
+
+.. module:: hittekaart_py
+
+    The ``hittekaart_py`` module provides a Python interface for hittekaart__
+    heatmap generation. Unlike previous modules, this is a binding using
+    PyO3__, and not a subprocess wrapper.
+
+.. __: https://gitlab.com/dunj3/hittekaart
+.. __: https://crates.io/crates/pyo3
+
+Example
+-------
+
+.. code-block:: python
+
+    from hittekaart_py import (
+        Track, HeatmapRenderer, Storage, generate
+    )
+
+    tracks = [
+        Track.from_file(b"Documents/track.gpx", None),
+        Track.from_coordinates([(45.0, 47.0)]),
+    ]
+    storage = Storage.Sqlite(b"/tmp/tiles.sqlite")
+    generate(tracks, HeatmapRenderer(), storage)
+
+Input and output
+----------------
+
+.. class:: Track
+
+    An in-memory representation of a track.
+
+    .. staticmethod:: from_file(path, compression)
+
+        Loads a track from the given file.
+
+        :param path: Path to the file.
+        :type path: bytes
+        :param compression: Decompression algorithm to use when reading the
+            file. Can be :obj:`None`, ``"gzip"`` or ``"brotli"``.
+        :type compression: str | None
+        :return: The created track.
+        :rtype: Track
+
+    .. staticmethod:: from_coordinates(coordinates)
+
+        Directly represents the given coordinates as a track.
+
+        :param coordinates: The coordinates as a list of longitude-latitude
+            pairs.
+        :type coordinates: list[tuple[float, float]]
+        :return: The created track.
+        :rtype: Track
+
+
+.. class:: Storage
+
+    Represents the output storage.
+
+    .. staticmethod:: Folder(path)
+
+        Output the tiles to the given folder. This will create a subdirectory
+        for every zoom level, then a directory for the x coordinate, then a
+        file ``y.png``.
+
+        Note that this will create many small files, which can waste space.
+
+        :param path: Path to the folder.
+        :type path: bytes
+        :return: The created storage.
+        :rtype: Storage
+
+    .. staticmethod:: Sqlite(path)
+
+        Output the tiles to the given SQLite database.
+
+        :param path: Path to the database.
+        :type path: bytes
+        :return: The created storage.
+        :rtype: Storage
+
+Renderers
+---------
+
+.. class:: HeatmapRenderer()
+
+    The renderer that generates a heatmap.
+
+.. class:: MarktileRenderer()
+
+    The renderer that will only mark visited tiles.
+
+.. class:: TilehuntRenderer(zoom)
+
+    The renderer that will mark visisted tiles at a fixed zoom level.
+
+    :param zoom: The zoom level.
+    :type zoom: int
+
+Functions
+---------
+
+.. function:: generate(items, renderer, storage)
+
+    Generates the tiles using the given renderer, and saves them to the given
+    storage.
+
+    :param items: The tracks to render.
+    :type items: ~typing.Iterable[Track]
+    :param renderer: The renderer to use.
+    :type renderer: HeatmapRenderer | MarktileRenderer | TilehuntRenderer
+    :param storage: The storage to output to.
+    :type storage: Storage
+
+.. function:: set_threads(threads)
+
+    Set the number of threads that hittekaart will use.
+
+    Note that this is a global function, it will affect all subsequent calls.
+
+    Note further that you may only call this function once, at startup. Calls
+    after the thread pool has been initialized (e.g. via a :func:`generate` or
+    :func:`set_threads` call) will raise an exception.
+
+    :param threads: Number of threads to use.
+    :type threads: int
+
+Errors
+------
+
+.. exception:: HitteError
+
+    Catch-all error for underlying hittekaart errors. See the string
+    description for the error cause.
diff --git a/doc/developer/module/modules.rst b/doc/developer/module/modules.rst
new file mode 100644
index 0000000..9585a5f
--- /dev/null
+++ b/doc/developer/module/modules.rst
@@ -0,0 +1,8 @@
+fietsboek
+=========
+
+.. toctree::
+   :maxdepth: 1
+
+   fietsboek
+   hittekaart_py
-- 
cgit v1.2.3