docs(mkdocs): add

.github/workflows/main.yml

@@ -149,3 +149,48 @@ jobs:
         run: gh release upload ${{ github.ref_name }} ${{ env.ASSET }} --repo ${{ github.repository }}
         env:
           GITHUB_TOKEN: ${{ github.token }}
+
+  docs-build:
+    name: Build docs
+    if: github.event_name == 'release' && github.event.action == 'created'
+    needs: [lint, tests]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install poetry
+        run: pipx install poetry
+
+      - uses: actions/setup-python@v5
+        with:
+          cache: poetry
+
+      - name: Install deps
+        run: poetry install
+
+      - name: Build docs
+        run: poetry run mkdocs build
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  docs-deploy:
+    name: Deploy docs
+    if: github.event.release.prerelease != true
+    needs: [docs-build]
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      id-token: write
+      pages: write
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.prettierignore

@@ -0,0 +1 @@
+docs/cli.md

Makefile

@@ -1,23 +1,27 @@
-.PHONY: all clean test checks
+.PHONY: all clean default install lock update checks pc test docs run
 
-install-all: install pc-install
+default: checks
 
 install:
+	pre-commit install
 	poetry install --sync
 
-pc-install:
-	pre-commit install
+lock:
+	poetry lock --no-update
 
-update-latest:
+update:
 	poetry up --latest
 
-checks: pc-run install lint test
+checks: pc install lint test
 
-pc-run:
+pc:
 	pre-commit run -a
 
 lint:
 	poetry run poe lint
 
 test:
 	poetry run poe test
+
+docs:
+	poetry run mkdocs serve

README.md

@@ -4,10 +4,13 @@
 
 [![PyPI version](https://img.shields.io/pypi/v/images-upload-cli)](https://pypi.org/project/images-upload-cli)
 [![AUR version](https://img.shields.io/aur/version/python-images-upload-cli)](https://aur.archlinux.org/packages/python-images-upload-cli)
+[![Documentation](https://img.shields.io/badge/docs-github-blue.svg)](https://deadnews.github.io/images-upload-cli)
 [![Main](https://github.com/DeadNews/images-upload-cli/actions/workflows/main.yml/badge.svg)](https://github.com/DeadNews/images-upload-cli/actions/workflows/main.yml)
 [![pre-commit.ci](https://results.pre-commit.ci/badge/github/DeadNews/images-upload-cli/main.svg)](https://results.pre-commit.ci/latest/github/DeadNews/images-upload-cli/main)
 [![codecov](https://codecov.io/gh/DeadNews/images-upload-cli/branch/main/graph/badge.svg?token=OCZDZIYPMC)](https://codecov.io/gh/DeadNews/images-upload-cli)
 
+**[Installation](#installation)** • **[Hostings](#hostings)** • **[Usage](#usage)** • **[Env Variables](#env-variables)**
+
 ## Installation
 
 PyPI
@@ -24,6 +27,8 @@ AUR
 yay -S python-images-upload-cli
 ```
 
+Windows executable attached to the github release.
+
 ## Hostings
 
 | host                                  | key required | return example                                       |
@@ -56,6 +61,8 @@ yay -S python-images-upload-cli
 
 ## Usage
 
+[CLI Reference](https://deadnews.github.io/images-upload-cli/cli/)
+
 ```sh
 Usage: images-upload-cli [OPTIONS] IMAGES...
 

docs/cli.md

@@ -0,0 +1,7 @@
+::: mkdocs-click
+    :prog_name: images-upload-cli
+    :module: images_upload_cli._cli
+    :command: cli
+    :style: table
+    :remove_ascii_art: True
+    :list_subcommands: True

docs/index.md

@@ -0,0 +1 @@
+--8<-- "README.md"

docs/scripts/gen_ref_nav.py

@@ -0,0 +1,41 @@
+#!/usr/bin/env python
+"""Generate the code reference pages and navigation."""
+
+from pathlib import Path
+
+import mkdocs_gen_files
+from mkdocs_gen_files.nav import Nav
+
+pkg_name = "images_upload_cli"
+nav = Nav()
+mod_symbol = '<code class="doc-symbol doc-symbol-nav doc-symbol-module"></code>'
+
+root = Path(__file__).parent.parent.parent
+src = root / "src"
+mods = sorted(src.rglob("*.py"), key=lambda p: (len(p.parts), p))
+
+for path in mods:
+    module_path = path.relative_to(src).with_suffix("")
+    doc_path = path.relative_to(src / pkg_name).with_suffix(".md")
+    full_doc_path = Path("reference", doc_path)
+
+    parts = tuple(module_path.parts)
+
+    if parts[-1] == "__init__":
+        parts = parts[:-1]
+        doc_path = doc_path.with_name("index.md")
+        full_doc_path = full_doc_path.with_name("index.md")
+    elif parts[-1].startswith("_"):
+        continue
+
+    nav_parts = [f"{mod_symbol} {part}" for part in parts]
+    nav[tuple(nav_parts)] = doc_path.as_posix()
+
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        ident = ".".join(parts)
+        fd.write(f"::: {ident}")
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, ".." / path.relative_to(root))
+
+with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())

mkdocs.yml

@@ -0,0 +1,90 @@
+site_name: images-upload-cli
+repo_url: https://github.com/deadnews/images-upload-cli
+edit_uri: blob/main/docs/
+
+nav:
+  - Overview: index.md
+  - API reference: reference/ # defer to gen-files + literate-nav
+  - CLI Reference: cli.md
+
+watch:
+  - src
+  - README.md
+
+theme:
+  name: material
+  palette:
+    - media: "(prefers-color-scheme)"
+      toggle:
+        name: Switch to light mode
+        icon: material/brightness-auto
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      toggle:
+        name: Switch to dark mode
+        icon: material/brightness-7
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        name: Switch to system preference
+        icon: material/brightness-4
+  features:
+    - content.action.edit
+    - content.action.view
+    - content.code.annotate
+    - content.code.copy
+    - content.code.select
+    - content.tooltips
+    - navigation.expand
+    - navigation.footer
+    - navigation.indexes
+    - navigation.sections
+    - navigation.tabs
+    - navigation.top
+    - navigation.tracking
+    - search.highlight
+    - search.share
+    - search.suggest
+    - toc.follow
+
+markdown_extensions:
+  - attr_list
+  - mkdocs-click
+  - pymdownx.snippets
+  - pymdownx.superfences
+  - toc:
+      permalink: true
+
+plugins:
+  - search
+  - gen-files:
+      scripts:
+        - docs/scripts/gen_ref_nav.py
+  - literate-nav:
+      nav_file: SUMMARY.md
+  - mkdocstrings:
+      handlers:
+        python:
+          paths: [src]
+          options:
+            docstring_options:
+              ignore_init_summary: true
+            docstring_section_style: table
+            docstring_style: google
+            filters: ["!^_"]
+            heading_level: 1
+            inherited_members: true
+            members_order: source
+            merge_init_into_class: true
+            separate_signature: true
+            show_root_full_path: false
+            show_root_heading: true
+            show_signature_annotations: true
+            show_submodules: true
+            show_symbol_type_heading: true
+            show_symbol_type_toc: true
+            signature_crossrefs: true
+            summary: true
+          import:
+            - https://docs.python.org/3/objects.inv
+            - https://pillow.readthedocs.io/en/stable/objects.inv