PDFCLOUD-6254: Convert structured documents to PDF

[datalogics-kam]

PDFCLOUD-6254

Why this change

The SDK could not convert structured Markdown, plain text, JSON, XML, or CSV documents through the documented POST /pdf capability. Callers had to construct untyped requests and could accidentally combine options that the service accepts only for particular source formats.

What changed (high level)

The synchronous and asynchronous clients now provide five format-specific helpers backed by Pydantic payload models and public structured-document types. Format-specific signatures keep incompatible options separate while shared page, typography, table, color, and output settings serialize to the API's structured_text_options object. Markdown image mappings accept uploaded resources and internally deduplicate their IDs.

Behavior changes

Callers upload a source document and pass its PdfRestFile to convert_markdown_to_pdf, convert_plain_text_to_pdf, convert_json_to_pdf, convert_xml_to_pdf, or convert_csv_to_pdf. Local validation rejects the wrong source format, multiple source files, unsupported Markdown image MIME types, and invalid literal or numeric options before transport. The SDK adds a runnable combined example, fixtures, generated API-guide links, and documented Literal value meanings. This is a feature release from 1.1.0 to 1.2.0; no existing public APIs change.

Validation

• uv run pytest -n auto --maxschedchunk 2 tests/test_convert_structured_documents_to_pdf.py — 121 passed, 10 expected matching-format skips.
• PDFREST_LIVE_BASE_URL=http://sleipnir:3000 uvx nox -s tests-3.11 -- tests/live/test_live_convert_structured_documents_to_pdf.py — 32 passed.
• Focused Ruff, BasedPyright, and pre-commit checks passed.
• Strict MkDocs build passed during the feature work. A full local pytest run remains environment-limited because the default localhost service does not provide the new structured conversion endpoints; the focused live run above targets the supplied service.

Risks and follow-ups

This is a stacked draft PR on #45: merge #45 first, then this PR. The base is pdfcloud-6243-pdf-with-added-shapes, so reviewers see only the structured-document conversion layer. The live coverage depends on the supplied sleipnir:3000 service. No breaking changes are intended.

[datalogics-kam]

Blocking dependency: PDFCLOUD-6287 blocks this work because the client
currently reproduces the upstream structured-text contract's open-ended
strings instead of preventing invalid requests.

In this PR, PdfStructuredTextPageSetup.size is str; the five font selectors
in PdfStructuredTextStyle are str/Sequence[str]; and the internal
Pydantic models enforce only min_length=1. language is likewise only a
non-empty string even though the OpenAPI description merely says it is
"typically" BCP 47. Consequently, values such as arialbold and Executive
pass client-side validation even though they are not valid structured-text font
and page-size identifiers.

This matters because the public font page documents watermark/add-text-style
names and API tokens, while the structured-text converter uses a different
APDFL catalog. See the upstream contract work and complete discrepancy list:
https://datalogics-jira.atlassian.net/browse/PDFCLOUD-6287

Please keep this PR blocked until PDFCLOUD-6287 publishes the authoritative
OpenAPI enums and validation. Then consume those contracts here as public
Literal aliases with accepted-values documentation, validate them in the
payload models, and add exhaustive accepted-value plus representative rejection
tests for sync and async callers.

GitHub does not permit the PR author to submit a Request changes review, so this
is recorded as a review comment; PDFCLOUD-6287 is formally linked as blocking
PDFCLOUD-6254 in Jira.