Skip to content

Add v2 documentation site - #302

Merged
jonmmease merged 67 commits into
mainfrom
jonmmease/build-docs
Sep 13, 2026
Merged

jonmmease merged 67 commits into
mainfrom
jonmmease/build-docs

Conversation

@jonmmease

@jonmmease jonmmease commented Sep 13, 2026 •

Copy link
Copy Markdown
Collaborator

Why

VlConvert 2.0 needs documentation that covers Rust, Python, CLI, and server workflows consistently.

What

Adds a Sphinx site with docs for Rust, Python, CLI, and server. Uses a system of fencing interface-specific code so that a single markdown file can be used for all applicable languages. Includes examples, migration guides, general and advanced topics, and an architecture page.

Improves the docs.rs documentation of the Rust crates by documenting the public APIs and making implementation modules private.

Remove the free Rust SVG conversion functions in favor of converter methods, which retain font and access settings without starting JavaScript workers.

jonmmease and others added 30 commits September 8, 2026 18:04
Fact-check every topic against the source and correct the errors found:
the nonexistent Python get_theme(), the malformed admin API link, the
server's rejected auto_google_fonts request field, Rust logger
installation, the CLI binary-output terminal guard, the Google Fonts
variant threshold semantics, redirect handling, and font introspection
returning only resolved fonts.

Reorder pages so terms are defined before use: HTML output moves to
Guides, image quality and logging move up, and the Server section
precedes Advanced with deployment profiles last. Add guides for
upgrading from 1.x, loading data and images, and the Google Fonts cache,
plus an interface comparison in the server overview. Fix the broken examples in the Python README.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Document that max_v8_heap_size_mb must be at least 64 MB and that the
Google Fonts variant threshold fails a conversion rather than skipping
families, in the Python stubs, binding docstrings, VlcConfig field docs,
and CLI help. Mark show_warnings as deprecated in the stubs, drop the
nonexistent auto_google_fonts request field from the allow_google_fonts
docstring, and raise the admin OpenAPI minimum for the heap cap to 64.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Local image files are now authorized the same way as data: the canonical
path must fall under an allowlisted directory. A filesystem base_url only
resolves relative hrefs and no longer grants read access on the SVG-based
output paths. The data ops and both image resolvers share one
authorize_local_path() helper, and the free svg_to_* functions keep an
explicit HTTP/HTTPS allowlist.

Close two bypasses found in review: SVG images drawn on the canvas are
parsed with a resolver that ignores nested file and URL references, and
HTTP redirects are followed manually so every hop is validated against
the allowlist under one 30-second deadline per request.

Make canvas rendering report image failures. The polyfill hands failed
loads to a runtime hook; access denials and unresolvable URLs (such as
about:invalid from a disabled base_url) fail the render like the SVG
resolver does, and other failures are logged as warnings. Skipped images
on the SVG path now log at warning level, and image denials say "image
url".

Describe images alongside data in the configuration docs, CLI help, and
guides, and document redirect checking, per-attempt timeouts, nested SVG
handling, and the behavior of each output type.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Relative data paths such as data/cars.json resolve against a pinned
vega-datasets release on the CDN by default, so they work without an
absolute URL. Describe that behavior and how base_url changes it.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Move the user-facing "How VlConvert Renders Charts" page under a new
top-level How It Works section and restore a crate-level architecture page
beside it. The architecture page is written at component level: it explains
that fonts drive text measurement and layout, how the worker runtime, startup
snapshot, and vendored modules keep conversion self-contained, and how the
unified data and image access policy applies, without per-worker
implementation detail.

Also correct the HTML Output guide: bundled pages inline plugin source and the
fonts VlConvert resolved, so only URL-referenced data and images and
unembedded fonts still need network access.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Replace the placeholder docs logo with the Vega "V" followed by a block letter
"C" drawn in the style of the Vega-Lite "VL" logo. The strokes, shadows, and
colors come from the vega/logos repository; the C uses a uniform 11 unit
thickness with chamfered outer corners and stepped terminals.

The SVGs live in a top-level logo/ directory. Sphinx and the pydata theme copy
them into the output _static/ directory at build time, and the docs-serve task
watches the directory for live reload.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Replace the layered dual-axis preview chart with a short bar chart and show
its Vega-Lite JSON above the rendered SVG. Center the chart and the row of
links beneath it, and offer every output as an icon-plus-format link: SVG,
PNG, PDF, bundled HTML, the compiled Vega spec, and an Editor URL that opens
the chart in the Vega Editor in a new tab.

The preview task now also writes the bundled HTML, the compiled Vega spec,
and the editor URL. The Sphinx config reads the URL file at build time and
exposes the editor link through a MyST substitution.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Google Fonts requested at the converter level, through the CLI flag, the
JSONC config, or Python configure(), were downloaded and used for text
measurement but never embedded in bundled SVG output or linked from plain
SVG output. Only per-call requests reached the SVG postprocessing step.

Union the configured and per-call requests when building the explicit family
set, in both SVG paths and in the font inspection path, and add a test that
renders the Google Fonts spec with configured fonts and checks for @font-face
when bundling and @import otherwise.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Each command's help output now sits under its own heading inside its group,
so the page navigation lists every command and each has an anchor.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@jonmmease jonmmease changed the title feat!: add v2 documentation and consolidate public Rust APIs Add v2 documentation and consolidate public Rust APIs Sep 13, 2026
Preserve FontOpts and keyword-only Python signatures alongside the API documentation cleanup. Update the version-parser test to use public exports and document patch-version selectors.
Replace the cache_size endpoint with cache and expose its read-only directory. Remove the cache path from infoz, update tests, and simplify server documentation.
@jonmmease jonmmease changed the title Add v2 documentation and consolidate public Rust APIs Add v2 documentation site Sep 13, 2026
@jonmmease
jonmmease marked this pull request as ready for review September 13, 2026 21:29
@jonmmease
jonmmease merged commit 03a02af into main Sep 13, 2026
11 checks passed
@jonmmease
jonmmease deleted the jonmmease/build-docs branch September 13, 2026 21:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant