Initial commit0.1.0

5 files changed, 114 insertions, 0 deletions

diff --git a/docs/advanced/api.rst b/docs/advanced/api.rst
new file mode 100644
index 0000000..61f6d01
--- /dev/null
+++ b/docs/advanced/api.rst
@@ -0,0 +1,14 @@
+GraphQL API & Versioning
+========================
+
+**hircine** exposes the `GraphQL <https://graphql.org>`_ endpoint on `/graphql
+</graphql>`_. When accessing this documentation on a running instance, clicking
+that link will open an interactive GraphQL IDE with a built-in documentation
+explorer.
+
+Versioning
+----------
+
+**hircine** uses `Semantic Versioning <https://semver.org>`_. The *public API*
+consists of both the frontend (command-line interface and web application) and
+the backend (GraphQL API and plugin infrastructure).
diff --git a/docs/advanced/hashing.rst b/docs/advanced/hashing.rst
new file mode 100644
index 0000000..90da3db
--- /dev/null
+++ b/docs/advanced/hashing.rst
@@ -0,0 +1,15 @@
+Hashing
+=======
+
+**hircine** uses the `BLAKE3 cryptographic hash function
+<https://github.com/BLAKE3-team/BLAKE3>`_ to compute hashes of archives and all
+its contained files.
+
+Whilst the latter files are hashed directly (i.e. their data is passed directly
+to the hash function), the *ZIP* archives are not. Instead, **hircine**
+calculates the hash of an archive by concatenating the hashes of *all* files
+within it in archive order.
+
+This means that changes to the archive files themselves will invalidate an
+archive's hash, but changes to *ZIP* compression levels or other basic metadata
+will not.
diff --git a/docs/advanced/image-processing.rst b/docs/advanced/image-processing.rst
new file mode 100644
index 0000000..dba71d0
--- /dev/null
+++ b/docs/advanced/image-processing.rst
@@ -0,0 +1,19 @@
+Image processing
+================
+
+Images are processed by the `Python Imaging Library (Pillow)
+<https://pillow.readthedocs.io/en/stable/index.html>`_ which supports a `wide
+variety
+<https://pillow.readthedocs.io/en/stable/handbook/image-file-formats.html>`_ of
+image formats. Processed images are stored in the :ref:`overview-object-store`
+using the `webp <https://developers.google.com/speed/webp>`_ format. Images are
+resampled using a `Lanczos filter
+<https://pillow.readthedocs.io/en/stable/handbook/concepts.html#PIL.Image.Resampling.LANCZOS>`_.
+
+Scaling
+-------
+
+By default, images are scaled to fit within the bounds of ``4200x2000`` pixels
+for display in the reader, and ``1680x800`` pixels for use as thumbnails. These
+values are optimized for larger displays and may be :ref:`changed in the
+configuration file <cfg-scale>` if you do not require such high resolutions.
diff --git a/docs/advanced/import-process.rst b/docs/advanced/import-process.rst
new file mode 100644
index 0000000..b33a927
--- /dev/null
+++ b/docs/advanced/import-process.rst
@@ -0,0 +1,53 @@
+Import process
+==============
+
+When importing a new archive, **hircine** will do the following:
+
+1. Calculate the hash of the archive its contents. See :doc:`/advanced/hashing`.
+2. Process each image for display in the application. See :doc:`/advanced/image-processing`.
+3. Collate all images in the archive in "natural" sort order. See `natsort
+   <https://github.com/SethMMorton/natsort?tab=readme-ov-file#quick-description>`_.
+4. Add the images and archive to the database.
+
+Status display
+--------------
+
+For each new or updated archive, **hircine** will report its status on the
+command line:
+
++---------+--------------------------------------------------------------------+
+| Symbol  | Meaning                                                            |
++=========+====================================================================+
+| ``[+]`` | This is a new archive.                                             |
++---------+--------------------------------------------------------------------+
+| ``[*]`` | This archive was updated (i.e. its modified time has changed).     |
++---------+--------------------------------------------------------------------+
+| ``[>]`` | This archive has been renamed.                                     |
++---------+--------------------------------------------------------------------+
+| ``[I]`` | This archive was ignored as it is a duplicate.                     |
++---------+--------------------------------------------------------------------+
+| ``[!]`` | This archive conflicts with another archive.                       |
++---------+--------------------------------------------------------------------+
+| ``[?]`` | This archive is referenced in the database but could not be found. |
++---------+--------------------------------------------------------------------+
+| ``[~]`` | The images from this archive were reprocessed.                     |
++---------+--------------------------------------------------------------------+
+
+
+
+Duplicates
+----------
+
+**hircine** will not add duplicate archives to its database. If two or more
+archives have the same content (i.e. their hashes match), a warning will be
+issued.
+
+Conflicts
+---------
+
+A conflict occurs when an archive hash in the database no longer matches the
+hash of the archive file on disk. **hircine** will take no further action other
+than printing an error message including the path of the archive and both
+hashes; it is up to the user to reconcile conflicts. An easy (but destructive)
+solution is to delete the affected archive in the web application and
+reimport it.
diff --git a/docs/advanced/index.rst b/docs/advanced/index.rst
new file mode 100644
index 0000000..3300030
--- /dev/null
+++ b/docs/advanced/index.rst
@@ -0,0 +1,13 @@
+Advanced topics
+===============
+
+This section describes advanced topics that are not crucial for usage of
+**hircine**, but may nevertheless be of interest.
+
+.. toctree::
+   :maxdepth: 1
+
+   import-process
+   hashing
+   image-processing
+   api