diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/administration/installation.rst | 31 | ||||
| -rw-r--r-- | doc/developer/module/hittekaart_py.rst | 149 | ||||
| -rw-r--r-- | doc/developer/module/modules.rst | 8 |
3 files changed, 180 insertions, 8 deletions
diff --git a/doc/administration/installation.rst b/doc/administration/installation.rst index b207784..13e03b5 100644 --- a/doc/administration/installation.rst +++ b/doc/administration/installation.rst @@ -6,14 +6,17 @@ This document will outline the installation process of Fietsboek, step-by-step. Requirements ------------ -Fietsboek has the following requirements (apart from the Python modules, which -will be installed by ``pip``): +Fietsboek has the following requirements: -* Python 3.10 or later -* A `redis <https://redis.com/>`__ server, used for caching and temporary data -* (Optionally) an SQL database server like `PostgreSQL - <https://www.postgresql.org/>`__ or `MariaDB <https://mariadb.org/>`__ (if - SQLite is not enough) +* A Linux system +* Python 3.11 or later +* A `redis <https://redis.com/>`__ server +* (Optionally) an SQL database server: + + * `PostgreSQL <https://www.postgresql.org/>`__ + +Other systems (such as BSD as operating system, or MariaDB as SQL server) might +work, but are not tested. In addition, if you run on a different interpreter than CPython, you might need a working Rust toolchain (``rustc`` and ``cargo``) installed. This is because @@ -97,6 +100,18 @@ parser to process the GPX files: .. _issue #7: https://gitlab.com/dunj3/fietsboek/-/issues/7 +Optional: Install Database Drivers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you decide to use a database other than SQLite, you must install the +required drivers: + +**PostgreSQL**: + +.. code:: bash + + .venv/bin/pip install psycopg2 + Configuring Fietsboek --------------------- @@ -119,7 +134,7 @@ other update tasks. You can use it to set up the initial database schema: instead of a specific version, you must also run ``.venv/bin/alembic -c production.ini upgrade head``. - See :doc:`../developer/updater` ("Furhter notes") for more information. + See :doc:`../developer/updater` ("Further notes") for more information. Adding an Administrator User ---------------------------- diff --git a/doc/developer/module/hittekaart_py.rst b/doc/developer/module/hittekaart_py.rst new file mode 100644 index 0000000..052c2b0 --- /dev/null +++ b/doc/developer/module/hittekaart_py.rst @@ -0,0 +1,149 @@ +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, Settings, Storage, generate + ) + + settings = Settings(threads=3) + tracks = [ + Track.from_file(b"Documents/track.gpx", None), + Track.from_coordinates([(45.0, 47.0)]), + ] + storage = Storage.Sqlite(b"/tmp/tiles.sqlite") + generate(settings, 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 + +Tile generation +--------------- + +.. class:: Settings(min_zoom=1, max_zoom=19, threads=0) + + Settings that apply to all renderers. + + .. attribute:: min_zoom + :type: int + + Smalles zoom level to generate tiles for. + + .. attribute:: max_zoom + :type: int + + Largest zoom level to generate tiles for. + + .. attribute:: threads + :type: int + + Number of threads to use for tile generation. + + Setting this to 0 will automatically determine the number of available + cores and use that many threads. + +.. function:: generate(settings, items, renderer, storage) + + Generates the tiles using the given renderer, and saves them to the given + storage. + + :param settings: The settings. + :type settings: Settings + :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 + +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 |