[docs/library] Add API documentation

docs/library/draw/base.md

@@ -0,0 +1,8 @@
+---
+title: "picharsso.draw.base - API - Picharsso"
+description: "This module defines an abstract base formatter."
+---
+
+# `base`
+
+::: picharsso.draw.base

docs/library/draw/braille.md

@@ -0,0 +1,8 @@
+---
+title: "picharsso.draw.braille - API - Picharsso"
+description: "This module defines a drawer for Braille style."
+---
+
+# `braille`
+
+::: picharsso.draw.braille

docs/library/draw/gradient.md

@@ -0,0 +1,8 @@
+---
+title: "picharsso.draw.gradient - API - Picharsso"
+description: "This module defines a drawer for gradient style."
+---
+
+# `gradient`
+
+::: picharsso.draw.gradient

docs/library/draw/index.md

@@ -0,0 +1,8 @@
+---
+title: "picharsso.draw - API - Picharsso"
+description: "This package defines drawers for different styles of text art."
+---
+
+# `draw`
+
+::: picharsso.draw.__init__

docs/library/format/ansi.md

@@ -0,0 +1,8 @@
+---
+title: "picharsso.format.ansi - API - Picharsso"
+description: "This module defines a formatter for the ANSI coloring scheme."
+---
+
+# `ansi`
+
+::: picharsso.format.ansi

docs/library/format/base.md

@@ -0,0 +1,8 @@
+---
+title: "picharsso.format.base - API - Picharsso"
+description: "This module defines an abstract base formatter."
+---
+
+# `base`
+
+::: picharsso.format.base

docs/library/format/html.md

@@ -0,0 +1,8 @@
+---
+title: "picharsso.format.html - API - Picharsso"
+description: "This module defines a formatter for HTML."
+---
+
+# `html`
+
+::: picharsso.format.html

docs/library/format/index.md

@@ -0,0 +1,8 @@
+---
+title: "picharsso.format - API - Picharsso"
+description: "This package defines formatters for different modes of text output."
+---
+
+# `format`
+
+::: picharsso.format.__init__

docs/library/meta.md

@@ -0,0 +1,8 @@
+---
+title: "picharsso.meta - API - Picharsso"
+description: "This module defines variables for the package metadata."
+---
+
+# `meta`
+
+::: picharsso.meta

docs/library/utils.md

@@ -0,0 +1,8 @@
+---
+title: "picharsso.utils - API - Picharsso"
+description: "This module defines utility functions that are used across the package."
+---
+
+# `utils`
+
+::: picharsso.utils

docs/snippets/chunks/draw/styles/braille/example.md

@@ -0,0 +1,8 @@
+??? example "Example"
+    Consider the following image:
+
+    --8<-- "docs/snippets/embed/subjects/apple.html"
+
+    Here's what it should look like:
+
+    --8<-- "docs/snippets/embed/outputs/demo/apple-braille.html"

docs/snippets/chunks/draw/styles/gradient/example.md

@@ -0,0 +1,8 @@
+??? example "Example"
+    Consider the following image:
+
+    --8<-- "docs/snippets/embed/subjects/apple.html"
+
+    Here's what it should look like:
+
+    --8<-- "docs/snippets/embed/outputs/demo/apple-gradient.html"

docs/snippets/embed/outputs/demo/apple-braille.html

@@ -0,0 +1,6 @@
+<div align="center">
+  <img
+    alt="Apple logo in text (Braille style)"
+    src="/assets/images/outputs/demo/apple-braille.webp"
+  />
+</div>

docs/snippets/embed/outputs/demo/apple-gradient.html

@@ -0,0 +1,6 @@
+<div align="center">
+  <img
+    alt="Apple logo in text (gradient style)"
+    src="/assets/images/outputs/demo/apple-gradient.webp"
+  />
+</div>

docs/snippets/embed/subjects/apple.html

@@ -0,0 +1,6 @@
+<div align="center">
+  <p>
+    <img alt="Apple logo" src="/assets/images/subjects/apple.webp" />
+  </p>
+  <em>Apple Computer [Rob Janoff, 1977]</em>
+</div>

docs/snippets/references/formats.md

@@ -0,0 +1,3 @@
+!!! question "Formats"
+    Refer to the [Formats documentation](/formats/)
+    to learn about the supported output formats.

docs/snippets/references/styles.md

@@ -0,0 +1,3 @@
+!!! question "Styles"
+    Refer to the [Styles documentation](/styles/)
+    for an in-depth guide to the **image processing behind Picharsso**.

src/__main__.py

@@ -1,3 +1,13 @@
+"""This module defines the behaviour of the package
+in a top-level script environment.
+
+The following command executes this script:
+
+```bash
+python -m picharsso
+```
+"""
+
 from .cli import main
 
 if __name__ == "__main__":

src/draw/__init__.py

@@ -1,9 +1,27 @@
+"""
+This package defines drawers for different styles of text art.
+
+--8<-- "docs/snippets/references/styles.md"
+"""
+
 from .gradient import GradientDrawer
 from .base import BaseDrawer, RESAMPLING_FILTERS, DEFAULT_RESAMPLING
 from .braille import BrailleDrawer
 
 DRAWERS: dict = {"gradient": GradientDrawer, "braille": BrailleDrawer}
+"""The collection of drawers."""
 
 
 def new_drawer(style, **kwargs):
+    """Creates a new drawer instance.
+
+    Args:
+        style (str): The style of the text art.
+        **kwargs (dict): Appropriate keyword arguments.
+                        See [`BaseDrawer`][picharsso.draw.base.BaseDrawer]
+                        and others.
+
+    Returns:
+        Type[picharsso.draw.BaseDrawer]: The new drawer instance.
+    """
     return DRAWERS[style](**kwargs)

src/draw/base.py

@@ -1,3 +1,9 @@
+"""
+This module defines an abstract base drawer.
+
+--8<-- "docs/snippets/references/styles.md"
+"""
+
 from abc import ABC, abstractmethod
 
 from PIL import Image
@@ -13,12 +19,45 @@
     "bicubic": Image.BICUBIC,
     "lanczos": Image.LANCZOS,
 }
+"""A collection of resampling filters.
+See [Pillow's Filters](https://pillow.readthedocs.io/en/stable/handbook/concepts.html#filters).
+"""
 
 DEFAULT_RESAMPLING: str = "nearest"
+"""The default resampling filter."""
 
 
 class BaseDrawer(ABC):
+    """
+    An abstract base drawer.
+
+    Attributes:
+        height (int): The desired height of the text in characters.
+        width (int): The desired width of the text in characters.
+        resample (int): The resampling filter.
+        format (Type[picharsso.format.BaseFormatter]): The formatter instance.
+
+    Note:
+        The following methods must be overwritten:
+
+        - [`calculate_size`][picharsso.draw.base.BaseDrawer.calculate_size]
+        - [`process`][picharsso.draw.base.BaseDrawer.process]
+    """
+
     def __init__(self, height=42, width=0, resample=DEFAULT_RESAMPLING, **kwargs):
+        """Initialization method.
+
+        Args:
+            height (Optional[int]): The desired height of the text in characters.
+            width (Optional[int]): The desired width of the text in characters.
+            resample (Optional[str]): The resampling filter.
+            **kwargs (dict): Appropriate keyword arguments.
+                    See [`BaseFormatter`][picharsso.format.base.BaseFormatter] and others.
+
+        Note:
+            When set as `0`, `height` is derived from `width` and vice versa.
+            This is done to preserve the aspect ratio of the image.
+        """
         self.height = None
         self.width = None
         self.resample = None
@@ -27,6 +66,15 @@ def __init__(self, height=42, width=0, resample=DEFAULT_RESAMPLING, **kwargs):
         self.format = new_formatter(**kwargs)
 
     def __call__(self, image):
+        """Applies processing and formatting on the `image`
+        and returns a single string.
+
+        Args:
+            image (PIL.Image.Image): The subject image.
+
+        Returns:
+            str: The string of text art.
+        """
         # Ensure that the image is in the `RGB` mode.
         image = ensure_rgb(image)
 
@@ -43,11 +91,41 @@ def __call__(self, image):
 
     @abstractmethod
     def calculate_size(self, image_size):
+        """Calculates the size of the image for processing the text matrix.
+
+        Args:
+            image_size (Tuple[int, int]): The height and width of the subject image.
+
+        Returns:
+            Tuple[int, int]: The size of the image.
+        """
 
     @abstractmethod
     def process(self, image):
+        """Converts an image to a matrix of text.
+
+        Args:
+            image (PIL.Image.Image): The subject image,
+                                    with `mode = "RGB"`,
+                                    and `size = (<height>, <width>)`.
+
+        Returns:
+            numpy.ndarray: The text matrix,
+                        with `shape = (<height>, <width>)`,
+                        and `dtype = str`.
+        """
 
     def set(self, height=None, width=None, resample=None):
+        """Sets attributes of the drawer instance.
+
+        Args:
+            height (Option[int]): Sets `height`.
+            width (Option[int]): Sets `width`.
+            resample (Option[str]): Sets `resample`.
+
+        Raises:
+            ValueError: If both `height` and `width` are set to `0`.
+        """
         # Set resampling filter
         if resample is not None:
             self.resample = RESAMPLING_FILTERS[resample]
@@ -62,3 +140,6 @@ def set(self, height=None, width=None, resample=None):
 
             self.height = new_h
             self.width = new_w
+
+
+__all__ = ["BaseDrawer", "RESAMPLING_FILTERS", "DEFAULT_RESAMPLING"]

src/draw/braille.py

@@ -1,13 +1,40 @@
+"""
+This module defines a drawer for the [Braille style](/styles/braille/).
+
+--8<-- "docs/snippets/chunks/draw/styles/braille/example.md"
+"""
+
 import numpy as np
 
 from .base import BaseDrawer
 from ..utils import submatrices
 
 DEFAULT_THRESHOLD: int = 64
+"""The default threshold grayscale intensity."""
 
 
 class BrailleDrawer(BaseDrawer):
+    """
+    A drawer for the [Braille style](/styles/braille/).
+
+    Inherits [`BaseDrawer`][picharsso.draw.base.BaseDrawer].
+
+    Attributes:
+        threshold (int): Threshold grayscale intensity for pixels to be considered.
+        kernel (numpy.ndarray): A hard-coded matrix relating the intensity to
+                             the Unicode values for Braille characters.
+        charset_array (numpy.ndarray): A matrix of all Braille characters,
+                                    indexed by their offsetted Unicode value.
+    """
+
     def __init__(self, threshold=DEFAULT_THRESHOLD, **kwargs):
+        """Initialization method.
+
+        Args:
+            threshold (Optional[int]): Threshold grayscale intensity
+                                    for pixels to be considered.
+        """
+
         super().__init__(**kwargs)
         self.threshold = None
         self.set(threshold=threshold)
@@ -55,7 +82,17 @@ def process(self, image):
         ]
 
     def set(self, threshold=None, **kwargs):
+        """Sets attributes of the drawer instance.
+
+        Args:
+            threshold (Optional[int]): Sets `threshold`.
+            **kwargs (dict): Appropriate keyword arguments.
+                    See [`BaseDrawer.set`][picharsso.draw.base.BaseDrawer.set].
+        """
         super().set(**kwargs)
 
         if threshold is not None:
             self.threshold = threshold
+
+
+__all__ = ["BrailleDrawer"]