Merge pull request #25 from loiccoyle/feat/docs

feat: generate and deploy docs

.github/workflows/docs.yml

@@ -0,0 +1,34 @@
+name: docs
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.12
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - name: Install poetry
+        uses: abatilo/actions-poetry@v2
+      - name: Install doc dependencies
+        run: poetry install --with docs
+      - name: Deploy docs
+        run: mkdocs gh-deploy --force

README.md

@@ -3,6 +3,7 @@
 
 <p align="center">
   <a href="https://github.com/loiccoyle/phomo/actions"><img src="https://github.com/loiccoyle/phomo/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://loiccoyle.com/phomo"><img src="https://img.shields.io/github/deployments/loiccoyle/phomo/github-pages?label=docs"></a>
   <a href="https://pypi.org/project/phomo/"><img src="https://img.shields.io/pypi/v/phomo"></a>
   <a href="./LICENSE.md"><img src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
   <img src="https://img.shields.io/badge/platform-linux%20%7C%20macOS%20%7C%20windows-informational">
@@ -103,7 +104,7 @@ options:
 
 - [x] look into parallelizing/multithreading
 - [x] look into non greedy tile assignments
+- [x] documentation
 - [ ] palette matching
-- [ ] documentation
 - [ ] shell completion
 - [ ] hex grid

docs/index.md

@@ -0,0 +1,49 @@
+<p align="center"><img src="https://i.imgur.com/rMze8u5.png" width="1000"></p>
+<p align="center"><b>Python package and CLI utility to create photo mosaics.</b></p>
+
+<p align="center">
+  <a href="https://github.com/loiccoyle/phomo/actions"><img src="https://github.com/loiccoyle/phomo/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://pypi.org/project/phomo/"><img src="https://img.shields.io/pypi/v/phomo"></a>
+  <a href="./LICENSE.md"><img src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
+  <img src="https://img.shields.io/badge/platform-linux%20%7C%20macOS%20%7C%20windows-informational">
+</p>
+
+# Overview
+
+`phomo` lets you quickly and easily create [photographic mosaics](https://en.wikipedia.org/wiki/Photographic_mosaic).
+
+# Features
+
+- **Simple:** CLI interface to create photo mosaics in seconds.
+- **Configurable:** Python package to create custom mosaics with ease.
+- **Fast:** GPU acceleration for large mosaics.
+
+# Installation
+
+`phomo` requires python 3.9 or later. It can be installed with or without GPU acceleration.
+
+/// admonition | Gpu acceleration
+For GPU acceleration you'll need a CUDA compatible GPU and the CUDA toolkit installed. See [numba docs](https://numba.readthedocs.io/en/stable/cuda/overview.html#requirements) for details.
+///
+
+## CLI
+
+If you only need the command line interface, you can use [`pipx`](https://pypa.github.io/pipx/). It installs the `phomo` package in an isolated environment and makes it easy to uninstall.
+
+```bash
+pipx install 'phomo'
+# or for gpu acceleration
+pipx install 'phomo[cuda]'
+```
+
+## Python package
+
+To install the Python package, use `pip`. It will install the CLI as well.
+It is recommended to use a
+[virtual environment](https://docs.python.org/3/tutorial/venv.html) to not mess with your system packages.
+
+```bash
+pip install 'phomo'
+# or for gpu acceleration
+pip install 'phomo[cuda]'
+```

docs/usage/cli.md

@@ -0,0 +1,51 @@
+# Command Line Interface
+
+## Basic Usage
+
+To use the `phomo` CLI, open your terminal and type:
+
+```bash
+phomo <master-image-path> <tile-directory-path> [options]
+```
+
+### Positional Arguements
+
+- `<master-image-path>`: Path to the master image we want to reconstruct as a photo mosaic.
+- `<tile-directory-path>`: Directory containing the tile images. The images in this directory will be used to reconstruct the master image. The more images, the better the mosaic.
+
+### Options
+
+- `-h, --help`: Show the help message and exit.
+- `-o OUTPUT, --output OUTPUT`: Specify the mosaic output path.
+- `-c MASTER_CROP_RATIO, --master-crop-ratio MASTER_CROP_RATIO`: Crop the master image to width/height ratio.
+- `-s MASTER_SIZE [MASTER_SIZE ...], --master-size MASTER_SIZE [MASTER_SIZE ...]`: Resize master image to width, height.
+- `-C TILE_CROP_RATIO, --tile-crop-ratio TILE_CROP_RATIO`: Crop the tile images to width/height ratio.
+- `-S TILE_SIZE [TILE_SIZE ...], --tile-size TILE_SIZE [TILE_SIZE ...]`: Resize tile images to width, height.
+- `-n N_APPEARANCES, --n-appearances N_APPEARANCES`: The number of times a tile can appear in the mosaic.
+- `-b, --black-and-white`: Convert master and tile images to black and white.
+- `-g, --show-grid`: Show the tile grid, don't build the mosaic.
+- `-d SUBDIVISIONS [SUBDIVISIONS ...], --subdivisions SUBDIVISIONS [SUBDIVISIONS ...]`: Grid subdivision thresholds.
+- `-G, --gpu`: Use GPU for distance matrix computation. Requires installing with `pip install 'phomo[cuda]'`.
+- `-m {greyscale,norm,luv_approx}, --metric {greyscale,norm,luv_approx}`: Distance metric.
+- `-j WORKERS, --workers WORKERS`: Number of workers use to run when computing the distance matrix.
+- `-v, --verbose`: Verbosity.
+
+## Examples
+
+### With 20x20 mosaic tiles and each tile appearing at most twice
+
+```bash
+phomo master.jpg tiles/ -o mosaic.jpg -S 20 20 -n 2
+```
+
+### Resize master image to 1080x1080 and use 10x10 tiles with the greyscale metric
+
+```bash
+phomo master.jpg tiles/ -o mosaic.jpg -s 1920 1080 -S 10 10 -m greyscale
+```
+
+### Subdivide tile regions with high contrast and run on the GPU
+
+```bash
+phomo master.jpg tiles/ -o mosaic.jpg -S 40 40 -G -d 0.1 0.1
+```

docs/usage/python_package/faces.ipynb

@@ -0,0 +1 @@
+../../../examples/faces.ipynb

docs/usage/python_package/metrics.ipynb

@@ -0,0 +1 @@
+../../../examples/metrics.ipynb

docs/usage/python_package/performance.ipynb

@@ -0,0 +1 @@
+../../../examples/performance.ipynb

docs/usage/python_package/performance_trick.ipynb

@@ -0,0 +1 @@
+../../../examples/performance_trick.ipynb