Skip to content

Commit 8b19c8c

Browse files
datalogics-kamdatalogics-kam
committed
docs: Revamp getting-started guide with Cloud-first setup
- Replaced the basic dependency installation instructions with a step-by-step Cloud-first onboarding guide for `pdfrest`. - Introduced examples for using `uv`, `pip`, and `Poetry` to set up the SDK. - Added API key export instructions and a `quickstart.py` sample program for testing the text extraction feature. - Enhanced reference sections with links to the official Cloud onboarding flow, API lab, and Python API reference. - Updated the `index.md` to provide a clearer overview of `pdfRest` and its relationship to the Python SDK. - Adjusted `.pre-commit-config.yaml` to exclude `docs/` from the `mdformat` hook. Assisted-by: Codex
1 parent e4858ce commit 8b19c8c

3 files changed

Lines changed: 170 additions & 20 deletions

File tree

‎.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

‎docs/getting-started.md‎

Lines changed: 117 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,126 @@
11
# Getting started
22

3-
## Install dependencies
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.
45

5-
```bash
6-
uv sync --group dev
7-
```
6+
## Before you begin
87

9-
## Run docs locally
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.
1011

11-
```bash
12-
uv run mkdocs serve
13-
```
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
1470

15-
Then open <http://127.0.0.1:8000>.
71+
Create `quickstart.py`:
1672

17-
## Build static docs
73+
```python
74+
from pathlib import Path
1875

19-
```bash
20-
uv run mkdocs build --strict
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)")
2196
```
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: 52 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,58 @@
11
# pdfrest documentation
22

3-
Welcome to the docs for `pdfrest`, a Python client for the PDFRest API.
3+
Welcome to the docs for `pdfrest`, a Python client for
4+
[pdfRest](https://pdfrest.com/).
45

5-
Use this site for:
6+
## What is pdfRest?
67

7-
- Project setup and local development guidance.
8-
- API reference generated from source docstrings.
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.
913

10-
## Documentation style
14+
Useful references:
1115

12-
- Pages are written in Markdown.
13-
- API docs are generated from Google-style Python docstrings.
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/)

0 commit comments

Comments
 (0)