[ev-br]

Previously, we seem to have only used in-place installs, with schemas folder being outside of the installable package root. This does not play well with a proper out-of-place installs. Therefore, switch to a more traditional src/ layout expected for a python project.

Specifically: the project lives at the repository root, with the package under src/. The JSON schemas are package
data, so a wheel carries them and a non-editable install works. The wheel also ships the test suite.

The project lives at the repository root, with the package under src/. The JSON schemas are package
data, so a wheel carries them and a non-editable install works. The wheel also ships the test suite.
The worked examples and demo.sh are not in this repository any more: they live in
benchx_examples and run in the e2e workflow.

benchx/                              repository root (132 tracked files)
├── pyproject.toml                   wheel = src/benchx (+ tests via force-include); readme = docs/benchx.md
├── uv.lock
├── README.md                        repo overview; also the docs site's landing page
├── CHANGELOG.md
├── LICENSE
├── zensical.toml                    docs site config (nav: Home, Design, Schemas, Use cases,
│                                    User stories, benchx; Schemas lists all nine schema pages)
│
├── src/
│   └── benchx/                      the package
│       ├── __init__.py
│       ├── cli.py  session.py  runner.py  compare.py  bench.py  …   (16 modules)
│       ├── adapters/  (7)           gbench, pyperf, asv, base, plus the two scripts
│       │                            run in the benchmark's own interpreter
│       │                            (asv_runtime.py, benchx_params.py)
│       ├── core/  (7)               catalog.py  loader.py  rules.py  validation.py  hashing.py  …
│       └── schemas/  (32 files)     package data, read by core/catalog.py
│           ├── measurement-result/0.1.0/{schema.json, examples/}
│           ├── work-order/  comparison-document/  config/  env-identity/
│           └── environment-policy/  identity-policy/  target-description/
│               target-provider-request/
│
├── tests/  (30 files)               conftest.py, fake_gbench.py, fixtures/
│                                    no __init__.py (tests do `from conftest import …`)
│
├── docs/  (28 files)                the site's sources
│   ├── benchx.md                    the implementation README (was benchx/README.md); also
│   │                                the package's long description on PyPI
│   ├── design/  use-cases/  user_stories/
│   ├── requirements.txt
│   └── index.md, schemas/           generated by tools/gen_docs.py, gitignored
│
├── tools/gen_docs.py                builds docs/index.md and docs/schemas/ from README.md
│                                    and src/benchx/schemas
└── .github/workflows/
    ├── tests.yml                    test matrix (editable) + `wheel` job (non-editable)
    ├── e2e.yml                      runs the benchx_examples; the repo is checked out as
    │                                `benchx/`, so the project is `benchx/` (its .venv: benchx/.venv).
    │                                The numpy-venvs job sets BENCHX_SRC=<workspace>/benchx: its
    │                                run.sh guesses the checkout from the package's parent
    │                                directory, which is src/ now, and finds no pyproject.toml
    └── docs.yml                     builds and deploys the site

What the wheel contains

98 files (93 package files and 5 of .dist-info metadata):

site-packages/benchx/
├── __init__.py, cli.py, …           the 16 modules
├── adapters/  core/                 (14 files)
├── schemas/                         32 files, found by core/catalog.py next to itself
└── tests/                           30 files, copied from the repo's tests/
                                     run with: python -m pytest --pyargs benchx

The sdist has 133 files (the sources, tests/, docs/, the CI workflows and the root files).

Runtime lookups

schemas:  $BENCHX_SCHEMAS  or  <package dir>/schemas       (core/catalog.py, Path(__file__).parents[1])

editable install:   src/benchx/schemas/    tests: the checkout's tests/ (benchx/tests does not exist)
wheel / sdist:      site-packages/benchx/schemas/    tests: site-packages/benchx/tests/

What moved where

Before	After
benchx/benchx/	src/benchx/
schemas/	src/benchx/schemas/
benchx/tests/	tests/ (and copied into the wheel as benchx/tests/)
benchx/pyproject.toml, benchx/uv.lock	pyproject.toml, uv.lock
benchx/README.md	docs/benchx.md
benchx/LICENSE, benchx/.gitignore	merged into the root LICENSE and .gitignore
benchx/examples/, benchx/demo.sh	gone from this repo (moved to benchx_examples by the e2e PR)
benchx/benchx in e2e.yml	benchx (and BENCHX_SRC for numpy-venvs)

Docs

Same pages as before, with the same navbar except for the Schemas entries. The built site differs on
the landing page (the Contents list) and the benchx page (the install line, plus one sentence on the
shipped tests), in the schema pages' "source" links, which point at src/benchx/schemas/…, and in the
navbar's Schemas section:

• removed: "Observed-context record", which pointed at a page that is never built (the schema was
  removed in Simplify context split and generalize identity using projections #63; Zensical does not validate nav entries, so the strict build never noticed);
• added: "Identity policy" and "Project configuration", whose pages were built but not linked.

[ev-br]

One significant change is that schemas have moved one level down.

TODO here:

• check that CI works
• double-check in-place and regular installs
• check that the docs make sense
• check that the READMEs make sense --- there were two, and now there's only one.

[rok]

Looks good! Mostly moving stuff around. CI seems to be passing ok, I propose we merge and do a separate PR for release automation.