PDFCLOUD-5582 Initial documentation

.github/workflows/docs.yml

@@ -0,0 +1,51 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          version: 0.9.18
+          python-version: "3.11"
+          enable-cache: true
+          cache-suffix: docs
+          cache-dependency-glob: uv.lock
+      - name: Synchronize project dependencies
+        run: uv sync --group dev
+      - name: Build documentation
+        run: uv run mkdocs build --strict
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - id: deployment
+        name: Deploy to GitHub Pages
+        uses: actions/deploy-pages@v4

.github/workflows/test-and-publish.yml

@@ -12,6 +12,24 @@ on:
       - published
 
 jobs:
+  docs-check:
+    name: Docs Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          version: 0.9.18
+          python-version: "3.11"
+          enable-cache: true
+          cache-suffix: test-and-publish
+          cache-dependency-glob: uv.lock
+      - name: Synchronize project dependencies
+        run: uv sync --group dev
+      - name: Build docs with MkDocs
+        run: uv run mkdocs build --strict
+
   tests:
     name: Tests (Python ${{ matrix.python-version }})
     runs-on: ubuntu-latest
@@ -100,6 +118,7 @@ jobs:
   publish:
     name: Publish to CodeArtifact
     needs:
+      - docs-check
       - tests
       - examples
     if: github.event_name == 'release'

.pre-commit-config.yaml

@@ -36,7 +36,7 @@ repos:
     hooks:
       - id: mdformat
         name: mdformat on non-.github files
-        exclude: ^.github/
+        exclude: ^(.github/|docs/)
         args: ["--wrap", "80", "--number"]
         additional_dependencies:
           - mdformat-gfm

AGENTS.md

@@ -8,9 +8,9 @@
   `tests/test_client.py`).
 - Workflow definitions are in `.github/workflows/`; adjust only when CI
   requirements change.
-- Documentation and contributor notes reside at the repo root (`README.md`,
-  `AGENTS.md`). Automation sessions live in `noxfile.py`; keep shared task logic
-  there.
+- Contributor notes reside at the repo root (`README.md`, `AGENTS.md`), while
+  the documentation site content lives in `docs/`. Automation sessions live in
+  `noxfile.py`; keep shared task logic there.
 
 ## Build, Test, and Development Commands
 
@@ -285,8 +285,9 @@
 
 ## CI & Publishing Notes
 
-- GitHub Actions run two workflows: `pre-commit` (no AWS credentials) and
-  `Test and Publish` (Python 3.10–3.14 matrix).
+- GitHub Actions run three workflows: `pre-commit` (no AWS credentials),
+  `Test and Publish` (Python 3.10–3.14 matrix), and `Docs` (GitHub Pages build
+  and deploy on `main` push/manual dispatch).
 - Only the release job assumes the AWS OIDC role to `uv build` and publish with
   `uv publish`.
 - Keep CodeArtifact credentials out of source control; day-to-day development

README.md

@@ -45,3 +45,17 @@ uvx nox -s class-coverage
 
 To reuse an existing `coverage/py<version>/coverage.json` without rerunning
 tests, add `-- --no-tests` (and optional `--coverage-json path`).
+
+## Documentation
+
+Run the docs site locally:
+
+```bash
+uv run mkdocs serve
+```
+
+Build the static documentation site:
+
+```bash
+uv run mkdocs build --strict
+```

docs/api-reference.md

@@ -0,0 +1,5 @@
+# API reference
+
+## Package
+
+::: pdfrest

docs/getting-started.md

@@ -0,0 +1,126 @@
+# Getting started
+
+This guide walks through a Cloud-first setup for `pdfrest` (the Python package
+published on PyPI) so you can make your first API call quickly.
+
+## Before you begin
+
+- A Python runtime (3.10+ recommended for this SDK).
+- A local PDF file to test with.
+- A pdfRest Cloud account and API key.
+
+For the official Cloud onboarding flow, see:
+
+- [pdfRest API Toolkit Cloud: Getting Started](https://docs.pdfrest.com/pdfrest-api-toolkit-cloud/getting-started/)
+- [Python API reference](api-reference.md)
+- [API Lab](https://pdfrest.com/apilab/)
+
+## 1. Create a project and install `pdfrest`
+
+### Recommended: uv
+
+=== "uv (Recommended)"
+    ```bash
+    mkdir pdfrest-quickstart
+    cd pdfrest-quickstart
+    uv init
+    uv add pdfrest
+    ```
+
+=== "pip + venv"
+    ```bash
+    mkdir pdfrest-quickstart
+    cd pdfrest-quickstart
+    python -m venv .venv
+    source .venv/bin/activate
+    pip install pdfrest
+    ```
+
+=== "Poetry"
+    ```bash
+    mkdir pdfrest-quickstart
+    cd pdfrest-quickstart
+    poetry init --no-interaction
+    poetry add pdfrest
+    ```
+
+## 2. Get your pdfRest Cloud API key
+
+1. Create or sign in to your account at [pdfRest.com](https://pdfrest.com/).
+2. Follow the Cloud onboarding steps in
+   [Getting Started](https://docs.pdfrest.com/pdfrest-api-toolkit-cloud/getting-started/).
+3. Copy your API key and export it as `PDFREST_API_KEY` in your shell.
+
+=== "macOS / Linux (bash/zsh)"
+    ```bash
+    export PDFREST_API_KEY="your-api-key-here"
+    ```
+
+=== "Windows PowerShell"
+    ```powershell
+    $env:PDFREST_API_KEY="your-api-key-here"
+    ```
+
+!!! tip
+    The [API Lab](https://pdfrest.com/apilab/) is useful for testing endpoints
+    interactively and generating starter code samples before integrating them
+    into your project.
+
+## 3. Add a short example program
+
+Create `quickstart.py`:
+
+```python
+from pathlib import Path
+
+from pdfrest import PdfRestClient
+
+input_pdf = Path("input.pdf")
+
+if not input_pdf.exists():
+    raise FileNotFoundError(
+        "Place a test PDF at ./input.pdf before running this script."
+    )
+
+with PdfRestClient() as client:
+    uploaded = client.files.create_from_paths([input_pdf])[0]
+    document = client.extract_pdf_text(uploaded, full_text="document")
+
+full_text = ""
+if document.full_text is not None and document.full_text.document_text is not None:
+    full_text = document.full_text.document_text
+
+print(f"Input file id: {uploaded.id}")
+print("Extracted text preview:")
+print(full_text[:500] if full_text else "(no text returned)")
+```
+
+What this script does:
+
+- Uploads `input.pdf` to pdfRest Cloud.
+- Calls `extract_pdf_text`.
+- Prints a short text preview from the response.
+
+## 4. Run the example
+
+=== "uv"
+    ```bash
+    uv run python quickstart.py
+    ```
+
+=== "pip + venv"
+    ```bash
+    python quickstart.py
+    ```
+
+=== "Poetry"
+    ```bash
+    poetry run python quickstart.py
+    ```
+
+## 5. Next steps
+
+- Browse endpoint options in the
+  [Python API reference](api-reference.md).
+- Explore additional endpoint behavior and payload examples in
+  [API Lab](https://pdfrest.com/apilab/).

docs/index.md

@@ -0,0 +1,58 @@
+# pdfrest documentation
+
+Welcome to the docs for `pdfrest`, a Python client for
+[pdfRest](https://pdfrest.com/).
+
+## What is pdfRest?
+
+[pdfRest](https://pdfrest.com/) is a cloud PDF processing platform that
+provides REST APIs for common document workflows such as conversion,
+compression, OCR, merge/split, and redaction. You send API requests to the
+pdfRest service, and pdfRest returns structured responses and processed file
+outputs.
+
+Useful references:
+
+- [pdfRest homepage](https://pdfrest.com/)
+- [API reference](https://pdfrest.com/apidocs/)
+- [API Lab (interactive testing)](https://pdfrest.com/apilab/)
+
+## How this Python API relates to pdfRest
+
+This repository provides the official Python SDK layer for calling pdfRest
+endpoints from Python applications.
+
+The SDK:
+
+- Targets the pdfRest API host (`https://api.pdfrest.com`) by default.
+- Exposes both sync and async clients (`PdfRestClient` and
+  `AsyncPdfRestClient`).
+- Provides typed request/response models and validation to make integrations
+  safer and easier to maintain.
+- Includes endpoint helpers that map Python method calls to pdfRest API routes.
+
+In short: pdfRest is the hosted API service, and this package is the Python
+developer interface for using that service in your code.
+
+## Ways to run pdfRest
+
+The pdfRest docs describe three deployment options:
+
+- [Cloud](https://docs.pdfrest.com/pdfrest-api-toolkit-cloud/getting-started/):
+  fastest path with pdfRest-managed infrastructure at `api.pdfrest.com`.
+- [On AWS](https://docs.pdfrest.com/pdfrest-api-toolkit-on-aws/getting-started/):
+  self-hosted deployment in your AWS environment (AMI or CloudFormation).
+- [Container](https://docs.pdfrest.com/pdfrest-api-toolkit-container/getting-started/):
+  self-hosted Docker/Kubernetes deployment for private cloud or on-prem.
+
+For this SDK, the integration surface stays consistent across all three:
+
+- Use the default client settings for Cloud.
+- Point the client `base_url` at your deployed endpoint for AWS or Container.
+- Keep using the same Python methods and payload models; only deployment
+  configuration changes.
+
+Reference:
+
+- [pdfRest documentation overview](https://docs.pdfrest.com/overview/)
+- [API reference guide directory](https://docs.pdfrest.com/api-reference-guides/directory/)

mkdocs.yml

@@ -0,0 +1,36 @@
+site_name: pdfrest
+site_description: Python client library for interacting with the PDFRest API
+repo_url: https://github.com/pdfrest/pdfrest-python
+docs_dir: docs
+site_dir: site
+strict: true
+
+theme:
+  name: material
+  features:
+    - content.code.copy
+
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          paths: [src]
+          options:
+            docstring_style: google
+            heading_level: 2
+            members_order: source
+            show_source: false
+            show_root_heading: true
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.superfences
+
+nav:
+  - Home: index.md
+  - Getting Started: getting-started.md
+  - API Reference: api-reference.md

pyproject.toml

@@ -36,6 +36,9 @@ dev = [
     "python-dotenv>=1.0.1",
     "diff-cover>=10.2.0",
     "rich>=14.1.0",
+    "mkdocs>=1.6.1",
+    "mkdocs-material>=9.7.1",
+    "mkdocstrings[python]>=1.0.3",
 ]
 
 [tool.pytest.ini_options]