diff options
Diffstat (limited to 'docs/usage')
| -rw-r--r-- | docs/usage/admin.rst | 58 | ||||
| -rw-r--r-- | docs/usage/configuration.rst | 41 | ||||
| -rw-r--r-- | docs/usage/filtering.rst | 45 | ||||
| -rw-r--r-- | docs/usage/getting-started.rst | 121 | ||||
| -rw-r--r-- | docs/usage/index.rst | 18 | ||||
| -rw-r--r-- | docs/usage/namespaces.rst | 43 | ||||
| -rw-r--r-- | docs/usage/reading.rst | 50 | ||||
| -rw-r--r-- | docs/usage/scraping.rst | 90 | ||||
| -rw-r--r-- | docs/usage/shortcuts.rst | 114 |
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. |