# 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:

```bash
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:

```bash
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:

```bash
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:

```bash
plesty docs serve
```

Open [http://127.0.0.1:8000](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:

```bash
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:

```bash
# 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:

```bash
# 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
```