Saving work

.github/dependabot.yml

@@ -6,7 +6,6 @@ updates:
   # Enable version updates for Python
   - package-ecosystem: "pip"
     target-branch: "develop"
-    # Look for a `Pipfile` in the `root` directory
     directory: "/"
     # Check for updates once a week
     schedule:

.github/workflows/ci.yml

@@ -172,7 +172,48 @@ jobs:
             path: dist/*
             if-no-files-found: error
             retention-days: 7
-
+  documentation:
+    name: Documentation
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    needs:
+      - lint
+    steps:
+      -
+        uses: actions/checkout@v4
+      -
+        name: Set up Python 3.10
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+          cache: 'pip'
+      -
+        name: Install Hatch
+        run: |
+          pip3 --quiet install --upgrade hatch
+      -
+        name: Build Documentation
+        run: |
+          hatch run docs:build
+      -
+        uses: actions/upload-artifact@v3
+        with:
+            name: documentation
+            path: site/*
+            if-no-files-found: error
+            retention-days: 7
+      -
+        name: Configure Git user
+        if: startsWith(github.ref, 'refs/tags/')
+        run: |
+          git config --local user.email "github-actions[bot]@users.noreply.github.com"
+          git config --local user.name "github-actions[bot]"
+      -
+        name: Deploy documentation
+        if: startsWith(github.ref, 'refs/tags/')
+        run: |
+          hatch run docs:deploy ${{ github.ref_name }}
   create-release:
     name: Release
     runs-on: ubuntu-latest

.gitignore

@@ -28,3 +28,7 @@ venv/
 
 # Possible PDF generated from testing
 tests/outputs/**
+
+# Documentation site
+site/
+.cache/

.pre-commit-config.yaml

@@ -11,6 +11,8 @@ repos:
       - id: check-json
         exclude: "tsconfig.*json"
       - id: check-yaml
+        args:
+          - "--unsafe"
       - id: check-toml
       - id: check-executables-have-shebangs
       - id: end-of-file-fixer

docs/.override/main.html

@@ -0,0 +1,8 @@
+{% extends "base.html" %}
+
+{% block outdated %}
+  You're not viewing the latest version.
+  <a href="{{ '../' ~ base_url }}">
+    <strong>Click here to go to latest.</strong>
+  </a>
+{% endblock %}

docs/api.md

@@ -0,0 +1,23 @@
+# Routes
+
+## Chromium
+
+### Common Options
+
+## LibreOffice
+
+### Options
+
+## PDF Engines
+
+### Options
+
+## Merge
+
+## Health
+
+## Metrics
+
+The metrics endpoint is not implemented yet.
+
+# Webhooks

docs/index.md

@@ -0,0 +1,76 @@
+This is a Python client for interfacing with [Gotenberg](https://gotenberg.dev/), which in turn is a wrapper around
+powerful tools for PDF generation and creation in various ways, using a stateless API. It's a very powerful tool
+to generate and manipulate PDFs.
+
+## Features
+
+- HTTP/2 enabled by default
+- Abstract away the handling of multi-part/form-data and deal with `Path`s instead
+- Based on the modern [httpx](https://github.com/encode/httpx) library
+- Full support for type hinting and concrete return types as much as possible
+- Nearly full test coverage run against an actual Gotenberg server for multiple Python and PyPy versions
+
+## Examples
+
+Converting a single HTML file into a PDF:
+
+```python
+from gotenberg_client import GotenbergClient
+
+with GotenbergClient("http://localhost:3000") as client:
+    with client.chromium.html_to_pdf() as route:
+      response = route.index("my-index.html").run()
+      Path("my-index.pdf").write_bytes(response.content)
+```
+
+Converting an HTML file with additional resources into a PDF:
+
+```python
+from gotenberg_client import GotenbergClient
+
+with GotenbergClient("http://localhost:3000") as client:
+    with client.chromium.html_to_pdf() as route:
+      response = route.index("my-index.html").resource("image.png").resource("style.css").run()
+      Path("my-index.pdf").write_bytes(response.content)
+```
+
+Converting an HTML file with additional resources into a PDF/A1a format:
+
+```python
+from gotenberg_client import GotenbergClient
+from gotenberg_client.options import PdfAFormat
+
+with GotenbergClient("http://localhost:3000") as client:
+    with client.chromium.html_to_pdf() as route:
+      response = route.index("my-index.html").resources(["image.png", "style.css"]).pdf_format(PdfAFormat.A1a).run()
+      Path("my-index.pdf").write_bytes(response.content)
+```
+
+Converting a URL into PDF, in landscape format
+
+```python
+from gotenberg_client import GotenbergClient
+from gotenberg_client.options import PageOrientation
+
+with GotenbergClient("http://localhost:3000") as client:
+    with client.chromium.html_to_pdf() as route:
+      response = route.url("https://hello.world").orient(PageOrientation.Landscape).run()
+      Path("my-world.pdf").write_bytes(response.content)
+```
+
+To ensure the proper clean up of all used resources, both the client and the route(s) should be
+used as context manager. If for some reason you cannot, you should `.close` the client and any
+routes:
+
+```python
+from gotenberg_client import GotenbergClient
+
+try:
+  client = GotenbergClient("http://localhost:3000")
+  try:
+    route = client.merge(["myfile.pdf", "otherfile.pdf"]).run()
+  finally:
+    route.close()
+finally:
+  client.close()
+```

mkdocs.yml

@@ -0,0 +1,73 @@
+site_name: Gotenberg Client
+
+site_url: https://stumpylog.github.io/gotenberg-client/
+site_author: Trenton H
+
+repo_name: stumpylog/gotenberg-client
+repo_url: https://github.com/stumpylog/gotenberg-client
+
+nav:
+  - "index.md"
+  - API: "api.md"
+  - "architecture.md"
+
+markdown_extensions:
+  - admonition
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - toc:
+      permalink: true
+
+theme:
+  name: material
+  custom_dir: docs/.override
+  features:
+    - navigation.tabs
+    - navigation.sections
+    - navigation.top
+    - toc.integrate
+    - search.suggest
+    - content.code.annotate
+    - pymdownx.superfences
+    - pymdownx.inlinehilite
+    - pymdownx.snippets
+    - footnotes
+  font:
+    text: Roboto
+    code: Roboto Mono
+  palette:
+    # Palette toggle for light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    # Palette toggle for dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+plugins:
+  - search
+  - social
+
+extra:
+  version:
+    provider: mike
+  analytics:
+    provider: google
+    property: G-YHHSXXB0FT
+  consent:
+    title: Cookie consent
+    description: >-
+      We use cookies to recognize your repeated visits and preferences, as well
+      as to measure the effectiveness of our documentation and whether users
+      find what they're searching for. With your consent, you're helping us to
+      make our documentation better.

pyproject.toml

@@ -34,7 +34,7 @@ dependencies = [
 ]
 
 [project.urls]
-Documentation = "https://github.com/stumpylog/gotenberg-client/#readme"
+Documentation = "https://stumpylog.github.io/gotenberg-client/"
 Issues = "https://github.com/stumpylog/gotenberg-client/issues"
 Source = "https://github.com/stumpylog/gotenberg-client/"
 Changelog = "https://github.com/stumpylog/gotenberg-client/blob/main/CHANGELOG.md"
@@ -95,6 +95,26 @@ dependencies = [
 check = ["pre-commit run --all-files"]
 update = ["pre-commit autoupdate"]
 
+[tool.hatch.envs.docs]
+template = "docs"
+detached = true
+dependencies = [
+  "mkdocs-material[imaging]~=9.5.2",
+  "mike~=2.0.0"
+]
+
+[tool.hatch.envs.docs.scripts]
+new = ["mkdocs new ."]
+build = ["mkdocs build"]
+serve = [
+  "mkdocs serve"
+]
+mike-help = ["mike serve --help"]
+deploy = [
+  "mike deploy --push --branch gh-pages --remote origin --update-aliases latest {args}",
+  "mike set-default --branch gh-pages --remote origin --push latest"
+]
+
 [tool.hatch.envs.lint]
 detached = true
 dependencies = [