Skip to content

Commit 021ea30

Browse files
datalogics-cgreendatalogics-cgreen
authored
Merge pull request #27 from datalogics-kam/pdfcloud-5582-documentation
PDFCLOUD-5582 additional documentation
2 parents df9491f + 1dea28f commit 021ea30

20 files changed

Lines changed: 4303 additions & 236 deletions

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

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,13 @@ jobs:
2929
run: uv sync --group dev
3030
- name: Build docs with MkDocs
3131
run: uv run mkdocs build --strict
32+
- name: Upload docs preview artifact
33+
if: github.event_name == 'pull_request'
34+
uses: actions/upload-artifact@v4
35+
with:
36+
name: docs-site
37+
path: site/
38+
retention-days: 7
3239

3340
tests:
3441
name: Tests (Python ${{ matrix.python-version }})

‎docs/api-guide.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# API guide
2+
3+
This guide organizes `PdfRestClient` and `AsyncPdfRestClient` methods by
4+
workflow, so you can quickly find the right call for a user task.
5+
6+
Notes:
7+
8+
- Every sync method has an async counterpart with the same name.
9+
- Sync client: [PdfRestClient][pdfrest.PdfRestClient]
10+
- Async client: [AsyncPdfRestClient][pdfrest.AsyncPdfRestClient]
11+
12+
## Start here: common flow
13+
14+
1. Upload file(s): [files.create_from_paths][pdfrest.PdfRestFilesClient.create_from_paths]
15+
2. Call one processing method from a category below.
16+
3. Download outputs: [files.read_bytes][pdfrest.PdfRestFilesClient.read_bytes] or
17+
[files.write_bytes][pdfrest.PdfRestFilesClient.write_bytes]
18+
4. (Optional) clean up: [files.delete][pdfrest.PdfRestFilesClient.delete]
19+
20+
## Service and file operations
21+
22+
Use these methods to check service status and manage uploaded resources.
23+
24+
- Health check:
25+
[up][pdfrest.PdfRestClient.up]
26+
- File helper:
27+
[files][pdfrest.PdfRestClient.files]
28+
- File upload and fetch:
29+
[files.create][pdfrest.PdfRestFilesClient.create],
30+
[files.create_from_paths][pdfrest.PdfRestFilesClient.create_from_paths],
31+
[files.create_from_urls][pdfrest.PdfRestFilesClient.create_from_urls],
32+
[files.get][pdfrest.PdfRestFilesClient.get]
33+
- File read/write:
34+
[files.read_bytes][pdfrest.PdfRestFilesClient.read_bytes],
35+
[files.read_text][pdfrest.PdfRestFilesClient.read_text],
36+
[files.read_json][pdfrest.PdfRestFilesClient.read_json],
37+
[files.write_bytes][pdfrest.PdfRestFilesClient.write_bytes],
38+
[files.stream][pdfrest.PdfRestFilesClient.stream]
39+
- File delete:
40+
[files.delete][pdfrest.PdfRestFilesClient.delete]
41+
42+
## Inspect, extract, summarize, and translate
43+
44+
Use this group when users need metadata or text intelligence.
45+
46+
- Metadata and document properties:
47+
[query_pdf_info][pdfrest.PdfRestClient.query_pdf_info]
48+
- OCR and text extraction:
49+
[ocr_pdf][pdfrest.PdfRestClient.ocr_pdf],
50+
[extract_pdf_text][pdfrest.PdfRestClient.extract_pdf_text],
51+
[extract_pdf_text_to_file][pdfrest.PdfRestClient.extract_pdf_text_to_file]
52+
- Image extraction:
53+
[extract_images][pdfrest.PdfRestClient.extract_images]
54+
- Summaries:
55+
[summarize_text][pdfrest.PdfRestClient.summarize_text],
56+
[summarize_text_to_file][pdfrest.PdfRestClient.summarize_text_to_file]
57+
- Translation:
58+
[translate_pdf_text][pdfrest.PdfRestClient.translate_pdf_text],
59+
[translate_pdf_text_to_file][pdfrest.PdfRestClient.translate_pdf_text_to_file]
60+
- Markdown output:
61+
[convert_to_markdown][pdfrest.PdfRestClient.convert_to_markdown]
62+
63+
## Compose, split, merge, and package
64+
65+
Use this group for document assembly and distribution.
66+
67+
- Create or partition documents:
68+
[blank_pdf][pdfrest.PdfRestClient.blank_pdf],
69+
[split_pdf][pdfrest.PdfRestClient.split_pdf]
70+
- Combine documents:
71+
[merge_pdfs][pdfrest.PdfRestClient.merge_pdfs]
72+
- Package/unpackage output sets:
73+
[zip_files][pdfrest.PdfRestClient.zip_files],
74+
[unzip_file][pdfrest.PdfRestClient.unzip_file]
75+
- Embed attachments:
76+
[add_attachment_to_pdf][pdfrest.PdfRestClient.add_attachment_to_pdf]
77+
78+
## Markup, branding, and redaction
79+
80+
Use this group to add visible content or remove sensitive content.
81+
82+
- Add overlays:
83+
[add_text_to_pdf][pdfrest.PdfRestClient.add_text_to_pdf],
84+
[add_image_to_pdf][pdfrest.PdfRestClient.add_image_to_pdf]
85+
- Watermarking:
86+
[watermark_pdf_with_text][pdfrest.PdfRestClient.watermark_pdf_with_text],
87+
[watermark_pdf_with_image][pdfrest.PdfRestClient.watermark_pdf_with_image]
88+
- Redaction workflow:
89+
[preview_redactions][pdfrest.PdfRestClient.preview_redactions] first,
90+
then [apply_redactions][pdfrest.PdfRestClient.apply_redactions]
91+
92+
## Security, signing, and compliance
93+
94+
Use this group for password protection, permissions, signatures, and standards.
95+
96+
- Permissions password:
97+
[add_permissions_password][pdfrest.PdfRestClient.add_permissions_password],
98+
[change_permissions_password][pdfrest.PdfRestClient.change_permissions_password],
99+
[remove_permissions_password][pdfrest.PdfRestClient.remove_permissions_password]
100+
- Open password:
101+
[add_open_password][pdfrest.PdfRestClient.add_open_password],
102+
[change_open_password][pdfrest.PdfRestClient.change_open_password],
103+
[remove_open_password][pdfrest.PdfRestClient.remove_open_password]
104+
- Digital signatures:
105+
[sign_pdf][pdfrest.PdfRestClient.sign_pdf]
106+
- Archival/print conformance:
107+
[convert_to_pdfa][pdfrest.PdfRestClient.convert_to_pdfa],
108+
[convert_to_pdfx][pdfrest.PdfRestClient.convert_to_pdfx]
109+
110+
## PDF cleanup and rendering normalization
111+
112+
Use this group to improve compatibility, performance, or file size.
113+
114+
- Size and optimization:
115+
[compress_pdf][pdfrest.PdfRestClient.compress_pdf],
116+
[linearize_pdf][pdfrest.PdfRestClient.linearize_pdf]
117+
- Flattening:
118+
[flatten_pdf_forms][pdfrest.PdfRestClient.flatten_pdf_forms],
119+
[flatten_annotations][pdfrest.PdfRestClient.flatten_annotations],
120+
[flatten_layers][pdfrest.PdfRestClient.flatten_layers],
121+
[flatten_transparencies][pdfrest.PdfRestClient.flatten_transparencies]
122+
- Raster and color normalization:
123+
[rasterize_pdf][pdfrest.PdfRestClient.rasterize_pdf],
124+
[convert_colors][pdfrest.PdfRestClient.convert_colors]
125+
126+
## Convert into or out of PDF
127+
128+
Use this group when the user starts with non-PDF content or needs downstream
129+
formats.
130+
131+
- Into PDF:
132+
[convert_office_to_pdf][pdfrest.PdfRestClient.convert_office_to_pdf],
133+
[convert_postscript_to_pdf][pdfrest.PdfRestClient.convert_postscript_to_pdf],
134+
[convert_email_to_pdf][pdfrest.PdfRestClient.convert_email_to_pdf],
135+
[convert_image_to_pdf][pdfrest.PdfRestClient.convert_image_to_pdf],
136+
[convert_html_to_pdf][pdfrest.PdfRestClient.convert_html_to_pdf],
137+
[convert_url_to_pdf][pdfrest.PdfRestClient.convert_url_to_pdf]
138+
- Out of PDF:
139+
[convert_to_word][pdfrest.PdfRestClient.convert_to_word],
140+
[convert_to_excel][pdfrest.PdfRestClient.convert_to_excel],
141+
[convert_to_powerpoint][pdfrest.PdfRestClient.convert_to_powerpoint],
142+
[convert_xfa_to_acroforms][pdfrest.PdfRestClient.convert_xfa_to_acroforms]
143+
- PDF to image:
144+
[convert_to_png][pdfrest.PdfRestClient.convert_to_png],
145+
[convert_to_bmp][pdfrest.PdfRestClient.convert_to_bmp],
146+
[convert_to_gif][pdfrest.PdfRestClient.convert_to_gif],
147+
[convert_to_jpeg][pdfrest.PdfRestClient.convert_to_jpeg],
148+
[convert_to_tiff][pdfrest.PdfRestClient.convert_to_tiff]
149+
150+
## Forms data workflows
151+
152+
Use this group when users need to transfer form field values in/out of PDFs.
153+
154+
- Import external form data into a PDF:
155+
[import_form_data][pdfrest.PdfRestClient.import_form_data]
156+
- Export form data from a PDF:
157+
[export_form_data][pdfrest.PdfRestClient.export_form_data]
158+
159+
## Async equivalents
160+
161+
For any sync method listed above, use the same method name on
162+
[AsyncPdfRestClient][pdfrest.AsyncPdfRestClient] when your app is async. For
163+
file helpers, use
164+
[AsyncPdfRestFilesClient][pdfrest.AsyncPdfRestFilesClient].

‎docs/api-reference.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,11 @@
33
## Package
44

55
::: pdfrest
6+
7+
## Public Types
8+
9+
::: pdfrest.types
10+
11+
## Public Models
12+
13+
::: pdfrest.models

‎docs/assets/favicon.ico‎

14.7 KB
Binary file not shown.

‎docs/assets/pdfrest-logo-dark-bg.png‎

7.27 KB
Loading

‎docs/assets/stylesheets/brand.css‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
:root > * {
2+
/* Keep body black-on-white. */
3+
--md-default-bg-color: #ffffff;
4+
--md-default-fg-color: #0c0c0c;
5+
--md-default-fg-color--light: rgba(12, 12, 12, 0.75);
6+
--md-default-fg-color--lighter: rgba(12, 12, 12, 0.55);
7+
--md-default-fg-color--lightest: rgba(12, 12, 12, 0.18);
8+
}
9+
10+
[data-md-color-primary="custom"] {
11+
--md-primary-fg-color: #0c0c0c;
12+
--md-primary-fg-color--light: #1a1a1a;
13+
--md-primary-fg-color--dark: #000000;
14+
--md-primary-bg-color: #ffffff;
15+
--md-primary-bg-color--light: rgba(255, 255, 255, 0.7);
16+
}
17+
18+
[data-md-color-accent="custom"] {
19+
--md-accent-fg-color: #d14081;
20+
--md-accent-fg-color--transparent: rgba(209, 64, 129, 0.12);
21+
}
22+
23+
[data-md-color-scheme="default"] {
24+
/* Body/docs links */
25+
--md-typeset-a-color: #5b2a86;
26+
}
27+
28+
/* Left sidebar grouping: keep Home + Getting Started visually separated
29+
from the rest of the navigation entries. */
30+
.md-sidebar--primary
31+
.md-nav--primary
32+
> .md-nav__list
33+
> .md-nav__item:nth-child(3) {
34+
border-top: 1px solid rgba(12, 12, 12, 0.18);
35+
margin-top: 0.5rem;
36+
padding-top: 0.5rem;
37+
}

0 commit comments

Comments
 (0)