PDFCLOUD-5582 additional documentation by datalogics-kam · Pull Request #27 · pdfrest/pdfrest-python

datalogics-kam · 2026-02-17T00:46:10Z

Summary

This PR expands and restructures the SDK docs so users can find the right client method quickly, understand typed inputs/outputs, and follow recommended file workflows with less trial and error.

It also promotes file helpers as first-class public SDK interfaces, adds comprehensive docstrings across public API surfaces, and refreshes docs branding/layout for a clearer reading experience.

What’s New (Outcomes)

PdfRestFilesClient and AsyncPdfRestFilesClient are now surfaced as documented public interfaces.
client.files is documented as the supported entry point (instead of constructing internals directly).
Added task-oriented docs:
- docs/api-guide.md (workflow-based API navigation with symbol links)
- docs/client-configuration.md (including per-call overrides)
- docs/using-files.md (upload/process/download/delete patterns)
API reference coverage expanded:
- docs/api-reference.md now includes package, public types, and public models.
API reference rendering improved via MkDocs/mkdocstrings:
- alphabetical member ordering
- separate signatures + annotation display
- signature crossrefs
- autorefs plugin enabled
Public model/type/client docs significantly expanded:
- richer docstrings on client methods, exceptions, models, and exported type aliases
- newly surfaced signature-related types (including PdfSignaturePoint) documented and exported
Docs UX/branding updates:
- custom theme override (overrides/main.html)
- brand CSS (docs/assets/stylesheets/brand.css)
- favicon/logo assets
- updated docs home/nav labels and links

User Impact

Faster method discovery by workflow.
Clearer file lifecycle guidance through client.files.
Better parity between typed SDK usage and generated docs.
Lower ambiguity around endpoint options, request overrides, and response models.
Cleaner reference browsing and improved docs visual identity.

Tooling / Lint Changes

Added Ruff pydocstyle enforcement in pyproject.toml:
- enabled D + D417
- configured lint.pydocstyle.convention = "google"
- scoped ignores for tests/**, scripts/**, examples/**, and noxfile.py

CI / Workflow Changes

Updated .github/workflows/test-and-publish.yml docs job:
- still builds docs with uv run mkdocs build --strict
- PR-only: uploads built site/ as docs-site artifact (retention-days: 7)
Python test workflow behavior is unchanged:
- matrix still runs across configured Python versions (3.10–3.14 in this repo)

Notes

This PR is primarily API-surface/documentation UX and lint-policy work.
Endpoint processing behavior is unchanged; updates focus on discoverability, docs clarity, and public SDK ergonomics.

netlify · 2026-02-17T21:44:56Z

✅ Deploy Preview for pdfrest-python ready!

Name	Link
🔨 Latest commit	`1dea28f`
🔍 Latest deploy log	https://app.netlify.com/projects/pdfrest-python/deploys/699768c5905b0b000ad39910
😎 Deploy Preview	https://deploy-preview-27--pdfrest-python.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

- Introduced `PdfRestFilesClient` and `AsyncPdfRestFilesClient` protocol interfaces for managing file operations, including methods to handle file uploads, retrievals, deletions, and content operations. - Updated the `PdfRestClient` and `AsyncPdfRestClient` classes to expose the file clients via the `files` property. - Updated `__all__` definitions in `__init__.py` and `client.py` to include the newly added clients. - Refactored `_FilesClient` and `_AsyncFilesClient` to adhere to the new interface protocols, improving type safety and clarity. Assisted-by: Codex

…tFilesClient - Added Google-style docstrings to all methods in `PdfRestFilesClient` and `AsyncPdfRestFilesClient`, documenting parameters, return types, and exceptions for improved clarity and usability. - This change enhances developer experience by providing comprehensive method documentation directly in the codebase. Assisted-by: Codex

- Added `line_length`, `separate_signature`, `show_signature_annotations`, and `signature_crossrefs` options in `mkdocstrings` plugin configuration. - Improves API documentation readability and presentation by better handling function signatures and annotations. Assisted-by: Codex

- Provided detailed docstrings for all properties, methods, and fields within public models to enhance clarity and usability of the API. - Added type-level descriptions for key API response types and utilities. - Improved coverage of metadata details, structured data, and edge cases for PDF processing operations. Assisted-by: Codex

- Updated `.github/workflows/test-and-publish.yml` to add a step for uploading documentation preview artifacts when triggered by pull requests. - Artifacts are retained for 7 days to aid in documentation review and testing. Assisted-by: Codex

- Added `client-configuration.md` detailing setup options for `PdfRestClient` and `AsyncPdfRestClient`, including parameters, timeout configurations, custom HTTPX client usage, and headers. - Updated `index.md` to include links to the new `getting-started.md` and `client-configuration.md` guides. - Modified `mkdocs.yml` to reflect the new navigation structure. Assisted-by: Codex

- Added `using-files.md` to provide a comprehensive guide on file operations in the SDK, covering uploads, downloads, metadata retrieval, and deletions. - Updated `index.md` to include a link to the new `using-files.md` guide. - Modified `mkdocs.yml` to reflect the updated navigation structure. Assisted-by: Codex

- Introduced `PdfSignaturePoint` to the public API for handling signature placement coordinates in PDF documents. - Enhanced docstrings for `PdfSignatureLocation`, `PdfSignatureDisplay`, `PdfNewSignatureConfiguration`, and related types with detailed attribute descriptions for improved clarity. - Updated `mkdocs.yml` to include the `autorefs` plugin for better cross-referencing in documentation. Assisted-by: Codex

- Enhanced docstrings for all methods in `PdfRestClient` with Google-style formatting, detailing parameters, return types, and exceptions for improved clarity and usability. - Included comprehensive descriptions for method functionality to assist developers in understanding each operation and its use cases. - Improved documentation of common arguments like `file`, `timeout`, and `extra_*` fields for consistency across methods. Assisted-by: Codex

- Changed `members_order` in `mkdocstrings` from `source` to `alphabetical` for better organization and readability of API documentation. Assisted-by: Codex

- Added `api-guide.md` to provide an organized overview of `PdfRestClient` and `AsyncPdfRestClient` methods, grouped by workflow and functionality. - Updated `index.md` to include a link to the new API guide. - Modified `mkdocs.yml` to reflect the updated navigation structure. Assisted-by: Codex

- Adjusted indentation and formatting of docstrings in all `PdfRestClient` methods to improve readability and alignment with Google-style documentation standards. - Ensured consistent structure for sections like `Args`, `Returns`, and `Raises` across all methods. Assisted-by: Codex

- Added a new section in `client-configuration.md` detailing per-call request override options for `PdfRestClient` and `AsyncPdfRestClient`. - Explained new arguments like `extra_query`, `extra_headers`, `extra_body`, and `timeout` with example usage. - Clarified behavior notes, including merging and overriding logic for query parameters, headers, and timeouts. Assisted-by: Codex

- Added a new `brand.css` for custom palette and branding styles. - Configured `mkdocs.yml` to use the custom primary and accent colors, logo (`pdfrest-logo-dark-bg.png`), and favicon (`favicon.ico`). - Registered `brand.css` as an additional stylesheet for use in the documentation site. Assisted-by: Codex

- Renamed the title in `index.md` to "pdfRest API Toolkit Python SDK." - Added a custom sidebar separator via `brand.css` for better navigation grouping. - Configured `mkdocs.yml` to use a new `custom_dir` for overrides and branding. - Introduced `overrides/main.html` to update the page `<title>` dynamically. Assisted-by: Codex

- Enabled Pydocstyle rules (D) in the `pyproject.toml` to enforce Google-style docstring conventions using Ruff. - Configured `tool.ruff.lint.pydocstyle.convention` to "google". - Applied Pydocstyle to specific file patterns like `scripts/**/*.py`, `examples/**/*.py`, and `noxfile.py`. Assisted-by: Codex

Ran `uv run ruff check --fix`

- Revised docstrings across `PdfRestClient`, `AsyncPdfRestFilesClient`, and exception classes to follow Google-style formatting. - Improved descriptions and added missing sections like `Args`, `Returns`, and `Raises` for better usability and readability. - Updated models and types with refined docstrings to clearly explain usage, structure, and expected behaviors. Assisted-by: Codex

datalogics-cgreen

Doc site appears to function as expected in the deployment preview

datalogics-kam requested a review from datalogics-cgreen February 17, 2026 00:49

datalogics-kam assigned datalogics-cgreen Feb 17, 2026

datalogics-kam marked this pull request as ready for review February 17, 2026 00:49

datalogics-kam force-pushed the pdfcloud-5582-documentation branch from 5a69556 to 48d67c2 Compare February 17, 2026 21:44

datalogics-kam force-pushed the pdfcloud-5582-documentation branch from e326fa1 to 04a24fc Compare February 19, 2026 17:54

datalogics-kam added 5 commits February 19, 2026 11:54

datalogics-kam force-pushed the pdfcloud-5582-documentation branch from 04a24fc to 825f704 Compare February 19, 2026 17:54

datalogics-kam added 8 commits February 19, 2026 12:10

mkdocs: Configure members_order as alphabetical in docstrings plugin

3461566

- Changed `members_order` in `mkdocstrings` from `source` to `alphabetical` for better organization and readability of API documentation. Assisted-by: Codex

datalogics-kam force-pushed the pdfcloud-5582-documentation branch from 3fb55ad to 365934f Compare February 19, 2026 18:10

datalogics-kam added 5 commits February 19, 2026 12:36

ruff: Automated fixes to docstrings

b4a91ee

Ran `uv run ruff check --fix`

datalogics-cgreen approved these changes Feb 19, 2026

View reviewed changes

datalogics-cgreen merged commit 021ea30 into pdfrest:main Feb 19, 2026
19 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

PDFCLOUD-5582 additional documentation#27

PDFCLOUD-5582 additional documentation#27
datalogics-cgreen merged 18 commits intopdfrest:mainfrom
datalogics-kam:pdfcloud-5582-documentation

datalogics-kam commented Feb 17, 2026 •

edited

Loading

Uh oh!

netlify Bot commented Feb 17, 2026 •

edited

Loading

Uh oh!

datalogics-cgreen left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

datalogics-kam commented Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What’s New (Outcomes)

User Impact

Tooling / Lint Changes

CI / Workflow Changes

Notes

Uh oh!

netlify Bot commented Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for pdfrest-python ready!

Uh oh!

datalogics-cgreen left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

datalogics-kam commented Feb 17, 2026 •

edited

Loading

netlify Bot commented Feb 17, 2026 •

edited

Loading