Skip to content

Commit 0ab9fdd

Browse files
datalogics-cgreendatalogics-cgreen
authored
Merge pull request #24 from datalogics-kam/pdfcloud-5582-documentation
PDFCLOUD-5582 Initial documentation
2 parents ea5eb66 + 9a9504a commit 0ab9fdd

12 files changed

Lines changed: 642 additions & 6 deletions

‎.github/workflows/docs.yml‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
name: Docs
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
workflow_dispatch:
8+
9+
permissions:
10+
contents: read
11+
pages: write
12+
id-token: write
13+
14+
concurrency:
15+
group: pages
16+
cancel-in-progress: false
17+
18+
jobs:
19+
build:
20+
runs-on: ubuntu-latest
21+
steps:
22+
- uses: actions/checkout@v4
23+
- name: Setup Pages
24+
uses: actions/configure-pages@v5
25+
- name: Install uv
26+
uses: astral-sh/setup-uv@v6
27+
with:
28+
version: 0.9.18
29+
python-version: "3.11"
30+
enable-cache: true
31+
cache-suffix: docs
32+
cache-dependency-glob: uv.lock
33+
- name: Synchronize project dependencies
34+
run: uv sync --group dev
35+
- name: Build documentation
36+
run: uv run mkdocs build --strict
37+
- name: Upload Pages artifact
38+
uses: actions/upload-pages-artifact@v3
39+
with:
40+
path: site
41+
42+
deploy:
43+
environment:
44+
name: github-pages
45+
url: ${{ steps.deployment.outputs.page_url }}
46+
needs: build
47+
runs-on: ubuntu-latest
48+
steps:
49+
- id: deployment
50+
name: Deploy to GitHub Pages
51+
uses: actions/deploy-pages@v4

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

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,24 @@ on:
1212
- published
1313

1414
jobs:
15+
docs-check:
16+
name: Docs Check
17+
runs-on: ubuntu-latest
18+
steps:
19+
- uses: actions/checkout@v4
20+
- name: Install uv
21+
uses: astral-sh/setup-uv@v6
22+
with:
23+
version: 0.9.18
24+
python-version: "3.11"
25+
enable-cache: true
26+
cache-suffix: test-and-publish
27+
cache-dependency-glob: uv.lock
28+
- name: Synchronize project dependencies
29+
run: uv sync --group dev
30+
- name: Build docs with MkDocs
31+
run: uv run mkdocs build --strict
32+
1533
tests:
1634
name: Tests (Python ${{ matrix.python-version }})
1735
runs-on: ubuntu-latest
@@ -100,6 +118,7 @@ jobs:
100118
publish:
101119
name: Publish to CodeArtifact
102120
needs:
121+
- docs-check
103122
- tests
104123
- examples
105124
if: github.event_name == 'release'

‎.idea/pdfrest-python.iml‎

Lines changed: 4 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎.pre-commit-config.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ repos:
3636
hooks:
3737
- id: mdformat
3838
name: mdformat on non-.github files
39-
exclude: ^.github/
39+
exclude: ^(.github/|docs/)
4040
args: ["--wrap", "80", "--number"]
4141
additional_dependencies:
4242
- mdformat-gfm

‎AGENTS.md‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,9 @@
88
`tests/test_client.py`).
99
- Workflow definitions are in `.github/workflows/`; adjust only when CI
1010
requirements change.
11-
- Documentation and contributor notes reside at the repo root (`README.md`,
12-
`AGENTS.md`). Automation sessions live in `noxfile.py`; keep shared task logic
13-
there.
11+
- Contributor notes reside at the repo root (`README.md`, `AGENTS.md`), while
12+
the documentation site content lives in `docs/`. Automation sessions live in
13+
`noxfile.py`; keep shared task logic there.
1414

1515
## Build, Test, and Development Commands
1616

@@ -311,8 +311,9 @@
311311

312312
## CI & Publishing Notes
313313

314-
- GitHub Actions run two workflows: `pre-commit` (no AWS credentials) and
315-
`Test and Publish` (Python 3.10–3.14 matrix).
314+
- GitHub Actions run three workflows: `pre-commit` (no AWS credentials),
315+
`Test and Publish` (Python 3.10–3.14 matrix), and `Docs` (GitHub Pages build
316+
and deploy on `main` push/manual dispatch).
316317
- Only the release job assumes the AWS OIDC role to `uv build` and publish with
317318
`uv publish`.
318319
- Keep CodeArtifact credentials out of source control; day-to-day development

‎README.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,3 +45,17 @@ uvx nox -s class-coverage
4545

4646
To reuse an existing `coverage/py<version>/coverage.json` without rerunning
4747
tests, add `-- --no-tests` (and optional `--coverage-json path`).
48+
49+
## Documentation
50+
51+
Run the docs site locally:
52+
53+
```bash
54+
uv run mkdocs serve
55+
```
56+
57+
Build the static documentation site:
58+
59+
```bash
60+
uv run mkdocs build --strict
61+
```

‎docs/api-reference.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# API reference
2+
3+
## Package
4+
5+
::: pdfrest

‎docs/getting-started.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# Getting started
2+
3+
This guide walks through a Cloud-first setup for `pdfrest` (the Python package
4+
published on PyPI) so you can make your first API call quickly.
5+
6+
## Before you begin
7+
8+
- A Python runtime (3.10+ recommended for this SDK).
9+
- A local PDF file to test with.
10+
- A pdfRest Cloud account and API key.
11+
12+
For the official Cloud onboarding flow, see:
13+
14+
- [pdfRest API Toolkit Cloud: Getting Started](https://docs.pdfrest.com/pdfrest-api-toolkit-cloud/getting-started/)
15+
- [Python API reference](api-reference.md)
16+
- [API Lab](https://pdfrest.com/apilab/)
17+
18+
## 1. Create a project and install `pdfrest`
19+
20+
### Recommended: uv
21+
22+
=== "uv (Recommended)"
23+
```bash
24+
mkdir pdfrest-quickstart
25+
cd pdfrest-quickstart
26+
uv init
27+
uv add pdfrest
28+
```
29+
30+
=== "pip + venv"
31+
```bash
32+
mkdir pdfrest-quickstart
33+
cd pdfrest-quickstart
34+
python -m venv .venv
35+
source .venv/bin/activate
36+
pip install pdfrest
37+
```
38+
39+
=== "Poetry"
40+
```bash
41+
mkdir pdfrest-quickstart
42+
cd pdfrest-quickstart
43+
poetry init --no-interaction
44+
poetry add pdfrest
45+
```
46+
47+
## 2. Get your pdfRest Cloud API key
48+
49+
1. Create or sign in to your account at [pdfRest.com](https://pdfrest.com/).
50+
2. Follow the Cloud onboarding steps in
51+
[Getting Started](https://docs.pdfrest.com/pdfrest-api-toolkit-cloud/getting-started/).
52+
3. Copy your API key and export it as `PDFREST_API_KEY` in your shell.
53+
54+
=== "macOS / Linux (bash/zsh)"
55+
```bash
56+
export PDFREST_API_KEY="your-api-key-here"
57+
```
58+
59+
=== "Windows PowerShell"
60+
```powershell
61+
$env:PDFREST_API_KEY="your-api-key-here"
62+
```
63+
64+
!!! tip
65+
The [API Lab](https://pdfrest.com/apilab/) is useful for testing endpoints
66+
interactively and generating starter code samples before integrating them
67+
into your project.
68+
69+
## 3. Add a short example program
70+
71+
Create `quickstart.py`:
72+
73+
```python
74+
from pathlib import Path
75+
76+
from pdfrest import PdfRestClient
77+
78+
input_pdf = Path("input.pdf")
79+
80+
if not input_pdf.exists():
81+
raise FileNotFoundError(
82+
"Place a test PDF at ./input.pdf before running this script."
83+
)
84+
85+
with PdfRestClient() as client:
86+
uploaded = client.files.create_from_paths([input_pdf])[0]
87+
document = client.extract_pdf_text(uploaded, full_text="document")
88+
89+
full_text = ""
90+
if document.full_text is not None and document.full_text.document_text is not None:
91+
full_text = document.full_text.document_text
92+
93+
print(f"Input file id: {uploaded.id}")
94+
print("Extracted text preview:")
95+
print(full_text[:500] if full_text else "(no text returned)")
96+
```
97+
98+
What this script does:
99+
100+
- Uploads `input.pdf` to pdfRest Cloud.
101+
- Calls `extract_pdf_text`.
102+
- Prints a short text preview from the response.
103+
104+
## 4. Run the example
105+
106+
=== "uv"
107+
```bash
108+
uv run python quickstart.py
109+
```
110+
111+
=== "pip + venv"
112+
```bash
113+
python quickstart.py
114+
```
115+
116+
=== "Poetry"
117+
```bash
118+
poetry run python quickstart.py
119+
```
120+
121+
## 5. Next steps
122+
123+
- Browse endpoint options in the
124+
[Python API reference](api-reference.md).
125+
- Explore additional endpoint behavior and payload examples in
126+
[API Lab](https://pdfrest.com/apilab/).

‎docs/index.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# pdfrest documentation
2+
3+
Welcome to the docs for `pdfrest`, a Python client for
4+
[pdfRest](https://pdfrest.com/).
5+
6+
## What is pdfRest?
7+
8+
[pdfRest](https://pdfrest.com/) is a cloud PDF processing platform that
9+
provides REST APIs for common document workflows such as conversion,
10+
compression, OCR, merge/split, and redaction. You send API requests to the
11+
pdfRest service, and pdfRest returns structured responses and processed file
12+
outputs.
13+
14+
Useful references:
15+
16+
- [pdfRest homepage](https://pdfrest.com/)
17+
- [API reference](https://pdfrest.com/apidocs/)
18+
- [API Lab (interactive testing)](https://pdfrest.com/apilab/)
19+
20+
## How this Python API relates to pdfRest
21+
22+
This repository provides the official Python SDK layer for calling pdfRest
23+
endpoints from Python applications.
24+
25+
The SDK:
26+
27+
- Targets the pdfRest API host (`https://api.pdfrest.com`) by default.
28+
- Exposes both sync and async clients (`PdfRestClient` and
29+
`AsyncPdfRestClient`).
30+
- Provides typed request/response models and validation to make integrations
31+
safer and easier to maintain.
32+
- Includes endpoint helpers that map Python method calls to pdfRest API routes.
33+
34+
In short: pdfRest is the hosted API service, and this package is the Python
35+
developer interface for using that service in your code.
36+
37+
## Ways to run pdfRest
38+
39+
The pdfRest docs describe three deployment options:
40+
41+
- [Cloud](https://docs.pdfrest.com/pdfrest-api-toolkit-cloud/getting-started/):
42+
fastest path with pdfRest-managed infrastructure at `api.pdfrest.com`.
43+
- [On AWS](https://docs.pdfrest.com/pdfrest-api-toolkit-on-aws/getting-started/):
44+
self-hosted deployment in your AWS environment (AMI or CloudFormation).
45+
- [Container](https://docs.pdfrest.com/pdfrest-api-toolkit-container/getting-started/):
46+
self-hosted Docker/Kubernetes deployment for private cloud or on-prem.
47+
48+
For this SDK, the integration surface stays consistent across all three:
49+
50+
- Use the default client settings for Cloud.
51+
- Point the client `base_url` at your deployed endpoint for AWS or Container.
52+
- Keep using the same Python methods and payload models; only deployment
53+
configuration changes.
54+
55+
Reference:
56+
57+
- [pdfRest documentation overview](https://docs.pdfrest.com/overview/)
58+
- [API reference guide directory](https://docs.pdfrest.com/api-reference-guides/directory/)

‎mkdocs.yml‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
site_name: pdfrest
2+
site_description: Python client library for interacting with the PDFRest API
3+
repo_url: https://github.com/pdfrest/pdfrest-python
4+
docs_dir: docs
5+
site_dir: site
6+
strict: true
7+
8+
theme:
9+
name: material
10+
features:
11+
- content.code.copy
12+
13+
plugins:
14+
- search
15+
- mkdocstrings:
16+
handlers:
17+
python:
18+
paths: [src]
19+
options:
20+
docstring_style: google
21+
heading_level: 2
22+
members_order: source
23+
show_source: false
24+
show_root_heading: true
25+
26+
markdown_extensions:
27+
- admonition
28+
- pymdownx.details
29+
- pymdownx.tabbed:
30+
alternate_style: true
31+
- pymdownx.superfences
32+
33+
nav:
34+
- Home: index.md
35+
- Getting Started: getting-started.md
36+
- API Reference: api-reference.md

0 commit comments

Comments
 (0)