Skip to content

docs: documentation rework + Vortex encoding-format specification#8690

Draft
mprammer wants to merge 1 commit into
developfrom
mp/spec
Draft

docs: documentation rework + Vortex encoding-format specification#8690
mprammer wants to merge 1 commit into
developfrom
mp/spec

Conversation

@mprammer

@mprammer mprammer commented Jul 8, 2026

Copy link
Copy Markdown
Contributor

Summary

Refreshes the Vortex documentation and adds a specification of the on-disk / on-wire format.

  • Documentation structure — a consolidated top-level Specification section, the developer guide grouped by audience, and refreshed concepts / user-guide / getting-started pages, with redirects for moved pages.
  • Encoding-format specification — the physical byte layout of the stable encodings: the cross-cutting validity contract, a per-encoding byte-layout reference for every stable encoding, and the array / scalar / file / dtype framing, plus a "reading a file" walkthrough.
  • Docs conformance harnessscripts/encoding_stability.py derives the stable-encoding set from the code, and scripts/check-docs-conformance.py checks the docs stay consistent with it; both are wired into CI as a guardrail against drift.

The warning-strict docs build is clean and the conformance checks pass.

🤖 Generated with Claude Code

@mprammer mprammer marked this pull request as draft July 8, 2026 19:43
@codspeed-hq

codspeed-hq Bot commented Jul 8, 2026

Copy link
Copy Markdown

Merging this PR will improve performance by 12.39%

⚠️ Unknown Walltime execution environment detected

Using the Walltime instrument on standard Hosted Runners will lead to inconsistent data.

For the most accurate results, we recommend using CodSpeed Macro Runners: bare-metal machines fine-tuned for performance measurement consistency.

⚡ 2 improved benchmarks
✅ 1643 untouched benchmarks
⏩ 4 skipped benchmarks1

Performance Changes

Mode Benchmark BASE HEAD Efficiency
Simulation chunked_varbinview_into_canonical[(100, 100)] 307.5 µs 272.5 µs +12.84%
Simulation bitwise_not_vortex_buffer_mut[128] 273.6 ns 244.4 ns +11.93%

Tip

Curious why this is faster? Comment @codspeedbot explain why this is faster on this PR, or directly use the CodSpeed MCP with your agent.


Comparing mp/spec (42cce13) with develop (4c762f7)

Open in CodSpeed

Footnotes

  1. 4 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports.

Documentation restructure (consolidated Specification section, developer guide grouped
by audience, refreshed concepts/user-guide) plus a specification of the on-disk/on-wire
encoding format (validity contract, per-encoding byte layouts, array/scalar/file/dtype
framing) and a docs-conformance harness that derives the stable-encoding set from the code.

Signed-off-by: mprammer <martin@spiraldb.com>
Co-Authored-By: Claude <noreply@anthropic.com>
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