Getting started

This guide walks through the typical workflow for creating and developing a Plesty-compliant device project.

1. Scaffold a new project

Name the project directory plesty-<name>, navigate into it, and run plesty init. The module name is automatically inferred by stripping the plesty- prefix:

mkdir plesty-power-meter && cd plesty-power-meter
plesty init device

This produces a plesty/power_meter/ source folder, a PyPI distribution named plesty-power-meter, and a package importable as plesty.power_meter. Alternatively, specify everything explicitly:

plesty --project-dir ~/projects/plesty-power-meter init device \
  --name power_meter \
  --author "Jane Doe" \
  --email jane@example.com

This generates a project pre-configured with the expected repository structure, pyproject.toml, example source files, CI pipeline (.gitlab-ci.yml), documentation stubs, and a CHANGELOG.md. A pre-push git hook is also installed automatically — it runs plesty check --standard nebula before every git push.

Use --ci-stages to select which pipeline stages to include, or --ci-stages "" to omit the CI file entirely.

2. Check compliance

Navigate into the project and run the compliance checker:

cd plesty-power-meter
plesty check

By default this checks against the Nebula level (all [SDK] gates). Add --standard pixel for a faster metadata + code hygiene only check, or --standard quantum to also run test coverage and semantic versioning gates locally. Fix any reported issues and re-run until the check passes.

3. Preview the documentation

Start a local documentation server with live reload:

plesty docs serve

Open http://127.0.0.1:8000 in your browser. Any changes to .md or .rst files in the docs/ directory are reflected immediately.

4. Apply license headers

Keep all Python files covered by the SPDX license header:

plesty license update

This reads author and maintainer information from pyproject.toml and writes the correct header to every .py file in the project.

5. Update project metadata

Use plesty update to change author info, the PyPI distribution name, or the CI pipeline at any time without re-scaffolding the project:

# Change the author
plesty update --author "Jane Doe" --email jane@example.com

# Rename the PyPI distribution
plesty update --name plesty-pm100d

# Trim the CI pipeline
plesty update --ci-stages "check,build,release"

6. Deploy documentation

Documentation deployment is handled automatically by the deploy-docs CI component when commits land on the default branch or a release tag is pushed. To deploy manually:

# Development snapshot
plesty docs deploy \
  https://gitlab-ci-token:${TOKEN}@gitlab.com/plesty/my-device.git \
  docs-build \
  --latest

# Versioned release
plesty docs deploy \
  https://gitlab-ci-token:${TOKEN}@gitlab.com/plesty/my-device.git \
  docs-build \
  --release