Initial commit0.1.0

9 files changed, 580 insertions, 0 deletions

diff --git a/docs/usage/admin.rst b/docs/usage/admin.rst
new file mode 100644
index 0000000..5fe2e90
--- /dev/null
+++ b/docs/usage/admin.rst
@@ -0,0 +1,58 @@
+Administrative tasks
+====================
+
+Administrative tasks are handled by the command-line interface. To get a quick
+overview of available commands, run:
+
+.. code-block:: console
+
+   $ hircine -h
+
+Updating the application
+------------------------
+
+To update **hircine**, download the newest wheel and install it in the virtual
+environment:
+
+.. code-block:: console
+
+   $ source <VENVDIR>/bin/activate
+   (.venv) $ python -m pip install <WHEEL>
+
+Running database migrations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+After the update it might be required to bring the database up-to-date. To do
+this, run:
+
+.. code-block:: console
+
+   $ hircine migrate
+
+A backup will be created automatically.
+
+Backing up the database
+-----------------------
+
+To save a current backup of the database into the ``backup/`` directory, run:
+
+.. code-block:: console
+
+   $ hircine backup
+
+To restore a previously saved backup, stop **hircine** and simply replace the
+``hircine.db`` file with the backup.
+
+Optimizing the database
+-----------------------
+
+To optimize the SQLite database, run:
+
+.. code-block:: console
+
+   $ hircine vacuum
+
+This is generally only recommended after deleting a large amount of data. Refer
+to the `SQLite documentation
+<https://www.sqlite.org/lang_vacuum.html#description>`_ for details on this
+process.
diff --git a/docs/usage/configuration.rst b/docs/usage/configuration.rst
new file mode 100644
index 0000000..e0f3669
--- /dev/null
+++ b/docs/usage/configuration.rst
@@ -0,0 +1,41 @@
+Configuration
+=============
+
+**hircine** looks for an optional configuration file named ``hircine.ini`` in
+its regular directory structure. Refer to Python's :mod:`configparser` module
+for details on its format.
+
+Sections
+--------
+
+.. _cfg-scale:
+
+import.scale
+^^^^^^^^^^^^
+
+This section is split into two subsections, ``full`` and ``thumb``. The former
+controls scaling for images displayed in the reader and the latter controls
+scaling for thumbnails. See :doc:`/advanced/image-processing`.
+
+The ``width`` and ``height`` settings in each subsection control the maximum
+pixel dimensions for the processed image. They are given as integers and must
+be greater than zero. The defaults are as follows:
+
+.. code-block:: ini
+
+   [import.scale.full]
+   width = 4200
+   height = 2000
+
+   [import.scale.thumb]
+   width = 1680
+   height = 800
+
+.. important::
+
+   Changes to these settings will only apply to newly processed image files. If
+   you want to reprocess your entire collection, run:
+
+   .. code-block:: console
+
+       $ hircine import -r
diff --git a/docs/usage/filtering.rst b/docs/usage/filtering.rst
new file mode 100644
index 0000000..05066fb
--- /dev/null
+++ b/docs/usage/filtering.rst
@@ -0,0 +1,45 @@
+Filtering
+=========
+
+A filter is a combination of predicates that have to be satisfied. **hircine**
+provides a filter interface that allows using almost any type of metadata as a
+predicate and can therefore build complex and expressive queries.
+
+.. image:: /_images/filtering.jpg
+   :align: center
+   :alt: Filtering comics
+
+If given multiple types of predicates, all of them have to match. If one type
+of predicate contains multiple selections, the selected mode determines how
+they are combined:
+
++----------------------+--------------------------------------------------+
+| Mode                 | Behaviour                                        |
++======================+==================================================+
+| ∀ ("for all")        | matches if all given entities match              |
++----------------------+--------------------------------------------------+
+| ∃ ("there exists")   | matches if any of the given entities match       |
++----------------------+--------------------------------------------------+
+| = ("exactly")        | matches if entities are present exactly as given |
++----------------------+--------------------------------------------------+
+
+For example, in the picture above, a comic only matches if *all* of the
+following is true:
+
+- It is tagged as ``female:idol`` or ``:tights``.
+- It is tagged with the artist ``40hara``.
+- It is rated as *Questionable*.
+- It is uncensored.
+- It is in any language except Japanese.
+
+Matching empty sets
+-------------------
+
+Each type of predicate may also match on the ∅ empty set. If enabled, the
+predicate only matches if the object does not contain any entities of that
+type.
+
+.. important::
+
+   If matching on the empty set, make sure there are no selections present in
+   the corresponding dropdown menu, as otherwise the filter will never match.
diff --git a/docs/usage/getting-started.rst b/docs/usage/getting-started.rst
new file mode 100644
index 0000000..60a167e
--- /dev/null
+++ b/docs/usage/getting-started.rst
@@ -0,0 +1,121 @@
+Getting started
+===============
+
+
+Importing archives
+------------------
+
+Place your archives in the ``content/`` directory and import them using the
+command-line interface:
+
+.. code-block:: console
+
+   $ hircine import
+
+As **hircine** can identify an archive by its contents, subsequent import jobs
+won't import the same archive again. Archives may also be renamed or moved
+freely within the ``content/`` directory; the next import job will recognize
+these changes automatically. Symbolic links will **not** be followed.
+
+.. note::
+
+   For a more technical breakdown see :doc:`/advanced/import-process`.
+
+Adding comics
+-------------
+
+Once the import job has finished, navigate to the archive tab in the web
+application and hit the refresh button [#f1]_ to load the newly added archives.
+Next, navigate to the archive that contains the comic you want to add. You'll
+be presented with an tabbed pane on the left and all the pages in the archive
+on the right.
+
+.. image:: /_images/archive.jpg
+   :align: center
+   :alt: The archive view
+
+By default, the pane shows the *Details* tab. Here you can see basic
+information on the archive and, once added, a list of comics from this archive.
+Clicking on a page will open the reader interface.
+
+.. note::
+
+   Once a comic has been added, you may specify its reading direction and page
+   layout. However, in archive view, the reader always defaults to
+   left-to-right single-page. For more information on the reader interface, see
+   :doc:`/usage/reading`.
+
+To add a new comic, navigate to the *Edit* tab and click the button to enter
+selection mode. Now, instead of opening the reader interface, clicking on a
+page adds it to the current selection.
+
+.. tip::
+
+   When in selection mode you may use Ctrl+Click to access the reader interface
+   instead.
+
+Select all pages that you want to add to a new comic and click the *Add* button
+that has appeared. The newly added comic will appear below and the selection
+mode exits. You may now add further comics by the same process, or add pages to
+an already existing comic by clicking on the *Add* button that appears over
+each comic.
+
+.. tip::
+
+   Once all relevant pages from an archive have been allocated, you may mark
+   the archive as "organized". This will automatically happen once the last
+   page has been added to a comic.
+
+Next, click on the newly added comic.
+
+Editing comics
+--------------
+
+Comics use the same layout as archives - a tabbed pane on the left and comic
+pages on the right. Just like before, clicking a page will open the reader.
+Navigate to the *Edit* tab to start annotating the comic with metadata.
+
+.. image:: /_images/comic-edit.jpg
+   :align: center
+   :alt: Editing a comic
+
+The top section of the edit form controls basic information about a comic,
+whilst the bottom section contains dropdown fields for the user-managed
+metadata categories. The picture above shows two categories that already have a
+selection, but for you these lists will be empty.
+
+Adding metadata
+---------------
+
+To add new metadata entities, navigate to the respective tab in the web
+application and hit the *Add* button in the top right corner. Alternatively,
+new entities may be added *at any time* using :ref:`shortcuts
+<shortcut-metadata>`.
+
+Let's add a new character. Hit ``nh`` on your keyboard, type in the character's
+name in the modal that appears and confirm by clicking on *Save* or hitting the
+``Enter`` key. The character is now available in the *Characters* dropdown.
+Select it there and save your changes - the comic is now tagged with this
+character.
+
+Removing comic pages
+--------------------
+
+Comic pages may be removed in the *Edit* tab by entering selection mode,
+selecting the pages that should be removed, and clicking the *Remove selected
+pages* button or hitting ``Delete``. Removed pages will be available again for
+allocation in the archive.
+
+Setting the cover
+-----------------
+
+The cover of a comic or an archive may be set at any time outside of selection
+mode by control clicking a page.
+
+|
+
+.. rubric:: Footnotes
+
+.. [#f1] This is the only time you need to refresh something manually in the
+   web application. Care has been taken that all other elements update
+   automatically.
diff --git a/docs/usage/index.rst b/docs/usage/index.rst
new file mode 100644
index 0000000..a685ad8
--- /dev/null
+++ b/docs/usage/index.rst
@@ -0,0 +1,18 @@
+Usage
+=====
+
+**hircine** is mainly controlled via the web interface. The command-line
+interface handles various administrative tasks and, crucially, is used to
+import your archives into the application.
+
+.. toctree::
+   :maxdepth: 2
+
+   getting-started
+   namespaces
+   reading
+   filtering
+   scraping
+   shortcuts
+   admin
+   configuration
diff --git a/docs/usage/namespaces.rst b/docs/usage/namespaces.rst
new file mode 100644
index 0000000..4eacb14
--- /dev/null
+++ b/docs/usage/namespaces.rst
@@ -0,0 +1,43 @@
+Namespaces & Tags
+=================
+
+As :ref:`mentioned earlier <overview-tags>`, the use of namespaces is required
+when tagging comics. The user must also choose which namespaces a tag is
+applicable to. That means that in order for the :term:`qualified tag`
+``female:love interest`` to appear as a valid selection, the following must be
+true:
+
+1. The namespace ``female`` must exist.
+2. The tag ``love interest`` must exist.
+3. The tag ``love interest`` must specify ``female`` as a valid namespace.
+
+.. note::
+
+   Qualified tags that are subsequently rendered invalid will **not**
+   automatically be removed from comics. Whilst the qualified tag can no longer
+   be selected in the editing or filtering interface, it can still be removed
+   from the comic manually.
+
+Namespace sorting
+-----------------
+
+Namespaces may be configured with a "sort name". This name will be used when
+sorting lists of namespaces or qualified tags. If no such name is given, the
+namespace name is used for sorting instead.
+
+Tag descriptions
+----------------
+
+Tags may be annotated with a custom description that further explains how the
+tag should be used. This description will be displayed as a tooltip when
+hovering over a qualified tag.
+
+Qualified tag display
+---------------------
+
+When selecting from a list, qualified tags are displayed by combining the
+namespace and tag with a colon, like ``female:love interest``. In all other
+contexts, qualified tags are rendered as small pills that contain the tag name
+only. A small number of namespaces have special handling, however: *female*,
+*male*, *trans*, *mixed*, and *location*. These are displayed with a specific
+colour and icon.
diff --git a/docs/usage/reading.rst b/docs/usage/reading.rst
new file mode 100644
index 0000000..f48e4c6
--- /dev/null
+++ b/docs/usage/reading.rst
@@ -0,0 +1,50 @@
+Reading
+=======
+
+The reader interface may be accessed by clicking on any comic page. The reader
+overlay will then open with the selected page in view. There are two metadata
+settings that affect the reader, **Direction** and **Layout**. The former
+adjusts reading direction and the latter determines how many pages are rendered
+at once.
+
+Navigation
+----------
+
+The reader is controlled with the mouse or the keyboard. When displaying a
+single page, clicking on the left side of the image will advance left, whilst
+clicking on the right side of the image will advance right. Similarly, when
+displaying two pages, clicking on the left image will advance left while
+clicking on the right image will advance right.
+
+Additionally, the following keyboard shortcuts are available:
+
++-------------+----------------------------------------------------+
+| Key         | Action                                             |
++=============+====================================================+
+| Left Arrow  | Advance left.                                      |
++-------------+----------------------------------------------------+
+| Right Arrow | Advance right.                                     |
++-------------+----------------------------------------------------+
+| Down Arrow  | Advance to the next page in reading direction.     |
++-------------+                                                    |
+| Page Down   |                                                    |
++-------------+                                                    |
+| Space       |                                                    |
++-------------+----------------------------------------------------+
+| Up Arrow    | Advance to the previous page in reading direction. |
++-------------+                                                    |
+| Page Up     |                                                    |
++-------------+                                                    |
+| Backspace   |                                                    |
++-------------+----------------------------------------------------+
+
+Editing when reading
+--------------------
+
+A comic may be edited in the reader interface by opening the edit menu in the
+top left corner or hitting ``z``. Changes to **Direction** and **Layout** will
+be visible in the reader right away, but will only persist if saved. This makes
+it easy to preview changes.
+
+Pending changes will not be lost when closing the reader interface - they can
+still be modified and saved in the normal *Edit* tab.
diff --git a/docs/usage/scraping.rst b/docs/usage/scraping.rst
new file mode 100644
index 0000000..37bae98
--- /dev/null
+++ b/docs/usage/scraping.rst
@@ -0,0 +1,90 @@
+Scraping
+========
+
+**hircine** comes with a generic scraper interface that allows scraping comic
+metadata from virtually any source. A number of scrapers for common file
+formats and websites are :ref:`included <builtin-scrapers>` in the base
+installation. Refer to :doc:`/plugins/index` if you want to write your own.
+
+
+Scraper sources
+---------------
+
+Usually, a scraper will access a location on the web or a local file on your
+disk. The former may be an online API, whilst the latter may be a `JSON
+<https://www.json.org/json-en.html>`_ file like `gallery-dl
+<https://github.com/mikf/gallery-dl>`_'s ``info.json``.
+
+For local files, two locations are considered. The comic's archive may contain
+this file, or it may be stored as sidecar file alongside the archive in the
+``content/`` directory.
+
+.. _sidecar-files:
+
+Archive & sidecar files
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Sidecar files need to be prefixed with the full name of the archive. For
+example, if a scraper accesses a file named ``info.json`` for an archive
+``Hoshiiro GirlDrop Comic Anthology.zip``, the following locations will be
+considered:
+
++----------+-------------------------------------------------------------+
+| Location | Name                                                        |
++==========+=============================================================+
+| Archive  | ``info.json``                                               |
++----------+-------------------------------------------------------------+
+| Sidecar  | ``content/Hoshiiro GirlDrop Comic Anthology.zip.info.json`` |
++----------+-------------------------------------------------------------+
+
+.. note::
+
+   If a file exists in both locations, the sidecar file is preferred.
+
+.. _scraper-interface:
+
+Scraper interface
+-----------------
+
+If a comic has scrapers available, they will be shown in the *Scrape* tab.
+Selecting the desired scraper and clicking on the *Scrape* button will start
+the scraping process.
+
+.. image:: /_images/scraper.jpg
+   :align: center
+   :alt: Scraping a comic.
+
+Once the scraper has returned results, they are shown in the pane below. Only
+results that differ from existing comic metadata will be displayed.
+
+Metadata that should not be kept may be deselected. For groups with a larger
+set of entries, the selection may be inverted to quickly deselect the whole
+group, or to only select a few entries. Pressing the *Merge* button will update
+the comic with the selected metadata.
+
+Options
+^^^^^^^
+
+By default, **hircine** does not automatically create missing metadata entries.
+This can be controlled using the *Create missing items* option.
+
+.. note::
+
+   Scrapers always return :term:`qualified tags <qualified tag>` (the namespace
+   is set to ``none`` if it could not be determined). When requested to create
+   a missing qualified tag, the namespace and tag will be created (if needed),
+   and the tag will be marked as applicable to the namespace.
+
+   A qualified tag is considered to be missing if any of the following apply:
+
+   1. The namespace does not exist.
+   2. The tag does not exist.
+   3. The tag is not applicable to the namespace.
+
+
+Modifying scraper results
+-------------------------
+
+**hircine** allows modifying results that are returned by a scraper without
+having to change the scraper logic. Refer to the documentation on
+:doc:`/plugins/index` for more.
diff --git a/docs/usage/shortcuts.rst b/docs/usage/shortcuts.rst
new file mode 100644
index 0000000..b3f88bb
--- /dev/null
+++ b/docs/usage/shortcuts.rst
@@ -0,0 +1,114 @@
+Shortcuts
+=========
+
+**hircine** supports a number of shortcuts that are meant to streamline a few
+common actions. Shortcuts may be made up of multiple keys. In that case, type
+them in order.
+
+.. _shortcut-navigation:
+
+Navigation
+----------
+
+.. list-table::
+   :align: left
+   :header-rows: 1
+
+   * - Shortcut
+     - Navigates to
+   * - ``go``
+     - Home
+   * - ``gc``
+     - Comics
+   * - ``gn``
+     - Namespaces
+   * - ``gt``
+     - Tags
+   * - ``gh``
+     - Characters
+   * - ``gw``
+     - Worlds
+   * - ``ga``
+     - Artists
+   * - ``gi``
+     - Circles
+   * - ``gz``
+     - Archives
+   * - ``?``
+     - Help
+
+.. _shortcut-metadata:
+
+Adding metadata
+---------------
+
+.. list-table::
+   :align: left
+   :header-rows: 1
+
+   * - Shortcut
+     - Action
+   * - ``na``
+     - Add a new artist.
+   * - ``ni``
+     - Add a new circle.
+   * - ``nh``
+     - Add a new character.
+   * - ``nw``
+     - Add a new world.
+   * - ``nn``
+     - Add a new namespace.
+   * - ``nt``
+     - Add a new tag.
+
+.. _shortcut-reader:
+
+Reader
+------
+
+.. list-table::
+   :align: left
+   :header-rows: 1
+
+   * - Shortcut
+     - Action
+   * - ``z``
+     - Open edit menu.
+   * - ``Escape``
+     - Close reader.
+
+.. _shortcut-filtering:
+
+Filtering
+---------
+
+.. list-table::
+   :align: left
+   :header-rows: 1
+
+   * - Shortcut
+     - Action
+   * - ``F``
+     - Focus search.
+   * - ``f``
+     - Toggle favourites.
+   * - ``b``
+     - Toggle bookmarked.
+   * - ``o``
+     - Toggle organized.
+
+.. _shortcut-misc:
+
+Miscellaneous
+-------------
+
+.. list-table::
+   :align: left
+   :header-rows: 1
+
+   * - Shortcut
+     - Action
+   * - ``s``
+     - Toggle selection mode if available.
+   * - ``Delete``
+     - Delete selected items.