Initial commit0.1.0

6 files changed, 183 insertions, 0 deletions

diff --git a/docs/plugins/builtin.rst b/docs/plugins/builtin.rst
new file mode 100644
index 0000000..61d531f
--- /dev/null
+++ b/docs/plugins/builtin.rst
@@ -0,0 +1,16 @@
+Built-in plugins
+================
+
+**hircine** comes with a number of plugins already built-in. This page serves
+as a quick reference for users and developers alike.
+
+.. _builtin-scrapers:
+
+Scrapers
+--------
+
+.. autoclass:: hircine.plugins.scrapers.gallery_dl.GalleryDLScraper()
+
+.. autoclass:: hircine.plugins.scrapers.ehentai_api.EHentaiAPIScraper()
+
+.. autoclass:: hircine.plugins.scrapers.anchira.AnchiraYamlScraper()
diff --git a/docs/plugins/index.rst b/docs/plugins/index.rst
new file mode 100644
index 0000000..2263fa2
--- /dev/null
+++ b/docs/plugins/index.rst
@@ -0,0 +1,17 @@
+Plugins
+=======
+
+Plugins are `Python <https://www.python.org>`_ programs that use **hircine**'s
+plugin architecture to customize or enhance the behaviour of certain parts of
+the application.
+
+There are two types of plugins. **Scrapers** read and report metadata from
+arbitrary sources and **Transformers** may modify that metadata freely before
+it is shown in the :ref:`scraper-interface`. As such, transformers cater to the
+needs of a specific user (e.g. to ignore certain pieces of metadata).
+
+.. toctree::
+   :maxdepth: 1
+
+   builtin
+   writing/index
diff --git a/docs/plugins/writing/index.rst b/docs/plugins/writing/index.rst
new file mode 100644
index 0000000..42afebd
--- /dev/null
+++ b/docs/plugins/writing/index.rst
@@ -0,0 +1,20 @@
+Writing plugins
+===============
+
+Before writing plugins, please familiarize yourself with the basics of the
+:ref:`Python programming language <python:tutorial-index>`. It is also
+recommended to read the :doc:`packaging:overview`. **hircine** discovers
+plugins via :ref:`package metadata <packaging:plugin-entry-points>`, so it is
+also useful to have a basic understanding of the :ref:`packaging:entry-points`.
+
+The plugin examples on the following pages are a good place to start once you
+are ready. You may also have a look at the `source code
+<https://git.oriole.systems/hircine/tree/src/hircine/plugins/scrapers>`_ for
+the built-in scrapers.
+
+.. toctree::
+   :maxdepth: 1
+
+   scrapers
+   transformers
+   reference
diff --git a/docs/plugins/writing/reference.rst b/docs/plugins/writing/reference.rst
new file mode 100644
index 0000000..1be281e
--- /dev/null
+++ b/docs/plugins/writing/reference.rst
@@ -0,0 +1,51 @@
+Plugin API Reference
+====================
+
+.. _scraped-data:
+
+Scraped Data
+------------
+
+.. automodule:: hircine.scraper.types
+   :members:
+
+API Data
+--------
+
+.. autoclass:: hircine.api.types.FullComic
+   :members:
+   :inherited-members:
+   :undoc-members:
+   :exclude-members: cover
+
+.. autoclass:: hircine.api.types.Archive
+   :members:
+   :undoc-members:
+   :exclude-members: cover
+
+Enums
+-----
+
+.. autoclass:: hircine.enums.Category()
+   :members:
+   :undoc-members:
+
+.. autoclass:: hircine.enums.Censorship()
+   :members:
+   :undoc-members:
+
+.. autoclass:: hircine.enums.Direction()
+   :members:
+   :undoc-members:
+
+.. autoclass:: hircine.enums.Language()
+   :members:
+   :undoc-members:
+
+.. autoclass:: hircine.enums.Layout()
+   :members:
+   :undoc-members:
+
+.. autoclass:: hircine.enums.Rating()
+   :members:
+   :undoc-members:
diff --git a/docs/plugins/writing/scrapers.rst b/docs/plugins/writing/scrapers.rst
new file mode 100644
index 0000000..258d3a8
--- /dev/null
+++ b/docs/plugins/writing/scrapers.rst
@@ -0,0 +1,48 @@
+Scrapers
+========
+
+A scraper extends the abstract :class:`~hircine.scraper.Scraper` class and
+implements its :meth:`~hircine.scraper.Scraper.scrape` method. The latter is a
+generator function yielding :ref:`scraped-data`.
+
+.. autoclass:: hircine.scraper.Scraper
+   :members:
+   :special-members: __init__
+
+Exceptions
+----------
+
+A scraper may raise two kinds of exceptions:
+
+.. autoexception:: hircine.scraper.ScrapeWarning
+
+.. autoexception:: hircine.scraper.ScrapeError
+
+Utility functions
+-----------------
+
+.. automodule:: hircine.scraper.utils
+   :members:
+
+Registering a scraper
+---------------------
+
+To register your class as a scraper, place it into the ``hircine.scraper``
+:ref:`entry point group <packaging:entry-points>`. For example, put the
+following in a ``pyproject.toml`` file:
+
+.. code-block:: toml
+
+   [project.entry-points.'hircine.scraper']
+   my_scraper = 'myscraper.MyScraper'
+
+Example
+-------
+
+.. literalinclude:: /_examples/example_scraper.py
+   :language: python
+
+The scraper above will scrape a JSON file with the following structure:
+
+.. literalinclude:: /_examples/example_scraper.json
+   :language: json
diff --git a/docs/plugins/writing/transformers.rst b/docs/plugins/writing/transformers.rst
new file mode 100644
index 0000000..045058d
--- /dev/null
+++ b/docs/plugins/writing/transformers.rst
@@ -0,0 +1,31 @@
+Transformers
+============
+
+**hircine** supports modification of scraper results by the use of
+transformers. Transformers are functions that hook into the scraping process
+and may freely modify any :ref:`scraped-data` before it is shown to the user.
+
+A transformer is specified by decorating a generator function with the
+:func:`~hircine.plugins.transformer` decorator.
+
+.. autodecorator:: hircine.plugins.transformer
+
+.. autoclass:: hircine.scraper.ScraperInfo
+
+Registering transformers
+------------------------
+
+To register transformers, place them into a module in the
+``hircine.transformer`` :ref:`entry point group <packaging:entry-points>`. For
+example, put the following in a ``pyproject.toml`` file:
+
+.. code-block:: toml
+
+   [project.entry-points.'hircine.transformer']
+   my_transformers = 'mytransformers.transformers'
+
+Example
+-------
+
+.. literalinclude:: /_examples/example_transformer.py
+   :language: python