Workspace Setup

Directory layout, key environment variables, and editor setup for PLESTY development.

Directory layout

After pulling a module, the repo structure looks like this:

repos/
  core/
    plesty-sdk/
    plesty-lib/
    plesty-ci/
  hub/
    devices/
      thorlab/
        plesty-pm100d/
    analyzers/
    experiments/
  website/
    plesty-website/
    contributor-guide/
    reports/

Work always happens inside the repo directory. All plesty CLI commands and uv run commands are run from within repos///.

Virtual environment

uv sync creates .venv/ in the repo root. To use the environment:

# Run a command in the env
uv run plesty check

# Or activate it
source .venv/bin/activate
plesty check

The uv run form is preferred — it ensures the correct env without activation.

Key files

File Purpose
pyproject.toml Package metadata, dependencies, [tool.plesty] config
CHANGELOG.md Required by Gate 5; must be updated before each release
.gitlab-ci.yml CI pipeline using plesty-standard-ci component
.git/hooks/pre-push Pre-push hook that runs plesty check before every push
assets/param_schema.json Device parameter definitions (devices only)
assets/op_schema.json Device operation definitions (devices only)

The [tool.plesty] section

pyproject.toml carries module metadata read by plesty check:

[tool.plesty]
# standard derives from the release version (<0.1 pixel, <1.0 nebula, >=1.0
# quantum; no tag yet = pixel) — set standard = "quantum" to pin it instead.
module_type = "device"      # one of: device, experiment, analyzer, core

module_type activates the Device API Pipeline gate (d1) when set to "device".

CI/CD variables

The CI pipeline uses two variables:

Variable Purpose Where it comes from
CI_BOT_TOKEN Push docs to docs-build branch (Gate 12) Group-level — inherited automatically; nothing to set up per module
PYPI_TOKEN Publish to PyPI (Gate 14) Set per project under Settings → CI/CD → Variables (Masked + Protected)

Never add a project-level CI_BOT_TOKEN — it would shadow the inherited group token.