plesty-sdk 0.0.2.dev10__tar.gz → 0.1.0__tar.gz

{plesty_sdk-0.0.2.dev10 → plesty_sdk-0.1.0}/.gitignore

@@ -1,4 +1,5 @@
 .venv/
+.uv-cache/
 __pycache__/
 uv.lock
 .python-version

plesty_sdk-0.1.0/.gitlab-ci.yml

@@ -0,0 +1,40 @@
+stages:
+  - check
+  - test
+  - build
+  - release
+  - deploy
+
+variables:
+  # Required for versioningit: the runner must fetch full Git history and tags.
+  GIT_DEPTH: "0"
+
+include:
+  # Check compliance with Plesty standard
+  - component: $CI_SERVER_FQDN/plesty/plesty-ci/check-compliance@main
+    inputs:
+      stage: check
+
+  # Run tests
+  - component: $CI_SERVER_FQDN/plesty/plesty-ci/run-tests@main
+    inputs:
+      stage: test
+
+  # Build Python package and expose dist/ as an artifact
+  - component: $CI_SERVER_FQDN/plesty/plesty-ci/build-pkg@main
+    inputs:
+      stage: build
+      job_name: build-pkg
+
+  # Publish package to PyPI on release tags
+  - component: $CI_SERVER_FQDN/plesty/plesty-ci/publish-pypi@main
+    inputs:
+      stage: release
+      pypi_token: $PYPI_TOKEN
+      build_job_name: build-pkg
+
+  # Deploy documentation to dedicated documentation branch
+  - component: $CI_SERVER_FQDN/plesty/plesty-ci/deploy-docs@main
+    inputs:
+      stage: deploy
+      access_token: $CI_BOT_TOKEN

{plesty_sdk-0.0.2.dev10 → plesty_sdk-0.1.0}/PKG-INFO

@@ -1,17 +1,21 @@
 Metadata-Version: 2.4
 Name: plesty-sdk
-Version: 0.0.2.dev10
+Version: 0.1.0
 Summary: Command-line application for developing Python modules compliant with the Plesty standard.
 Author: Plesty Development Team
 License-File: COPYING
 License-File: COPYING.LESSER
 License-File: LICENSE
 Requires-Python: >=3.12
+Requires-Dist: bluesky>=1.14.6
 Requires-Dist: click>=3.8
+Requires-Dist: copier>=9.15.1
+Requires-Dist: licenseheaders>=0.8.8
 Requires-Dist: livereload>=2.7.1
 Requires-Dist: md2pdf>=3.1.1
 Requires-Dist: myst-parser>=5.0.0
 Requires-Dist: pydata-sphinx-theme==0.17.1
+Requires-Dist: pytest>=9.0.0
 Requires-Dist: ruff>=0.14
 Requires-Dist: sphinx-autoapi>=3.6.1
 Requires-Dist: sphinx-copybutton>=0.5.2
@@ -20,8 +24,8 @@ Requires-Dist: sphinx-external-toc>=1.1.0
 Requires-Dist: sphinx>=9.1.0
 Requires-Dist: sphinxcontrib-mermaid>=2.0.0
 Requires-Dist: watchfiles>=1.1.1
-Provides-Extra: pdf
-Requires-Dist: md2pdf>=3.1.1; extra == 'pdf'
+Provides-Extra: gui
+Requires-Dist: pyside6-essentials>=6.11.0; extra == 'gui'
 Description-Content-Type: text/markdown
 
 # plesty-sdk - Setting the Coding Standard

plesty_sdk-0.1.0/docs/commands/check.md

@@ -0,0 +1,56 @@
+# plesty check
+
+Validates a project against a Plesty compliance standard. Runs the `ruff` linter and checks
+GUI and device-specific requirements depending on the chosen level.
+
+```bash
+plesty check [--standard LEVEL] [--device]
+```
+
+## Options
+
+| Option | Default | Description |
+|---|---|---|
+| `--standard` | `pixel` | Compliance level: `pixel`, `nebula`, or `quantum` |
+| `--device` | off | Also run device-specific compliance checks |
+
+## Compliance levels
+
+### Pixel
+
+The entry-level standard. Covers the essentials every Plesty module must have:
+
+- Code hygiene: the project must pass `ruff` linting rules.
+- Repository structure: required files and directories are present.
+- Documented example: at least one usage example exists.
+
+### Nebula
+
+Everything in Pixel, plus:
+
+- Extended documentation requirements.
+- Data standard compliance.
+- Basic interface checks (if applicable).
+- Partial testing coverage.
+- GUI structure is validated if a GUI is present.
+
+### Quantum
+
+The highest standard, intended for actively maintained production modules:
+
+- Full check of all standardisation goals.
+- Complete interface and version management requirements.
+- Dependency management and maintenance indicators.
+
+## Examples
+
+```bash
+# Default Pixel check in the current directory
+plesty check
+
+# Nebula check including device-specific rules
+plesty check --standard nebula --device
+
+# Quantum check on a project in another directory
+plesty --project-dir ../plesty-power-meter-device check --standard quantum --device
+```

plesty_sdk-0.1.0/docs/commands/docs.md

@@ -0,0 +1,71 @@
+# plesty docs
+
+Build, preview, and deploy the Sphinx documentation for a Plesty project.
+
+## Subcommands
+
+- `plesty docs serve` — local preview with live reload
+- `plesty docs deploy` — publish to a remote pages branch
+
+---
+
+## serve
+
+```bash
+plesty docs serve [--dev-addr IP:PORT]
+```
+
+Starts a local web server that renders the project documentation and automatically reloads
+whenever a `.md` or `.rst` file changes. Useful during active documentation writing.
+
+### Options
+
+| Option | Default | Description |
+|---|---|---|
+| `--dev-addr` | `127.0.0.1:8000` | Host and port for the preview server |
+
+### Example
+
+```bash
+# Default address
+plesty docs serve
+
+# Listen on all interfaces at a custom port
+plesty docs serve --dev-addr 0.0.0.0:9000
+```
+
+Press **Ctrl+C** to stop the server.
+
+---
+
+## deploy
+
+```bash
+plesty docs deploy --remote-url URL --target-branch BRANCH [--release]
+```
+
+Builds the Sphinx documentation and pushes it to the specified branch on a remote repository,
+suitable for GitLab Pages or GitHub Pages.
+
+### Options
+
+| Option | Default | Description |
+|---|---|---|
+| `--remote-url` | required | Git remote URL to push the built docs to |
+| `--target-branch` | required | Branch that serves the documentation pages |
+| `--release` | off | Build as a versioned release; without this flag the docs are published as the latest development snapshot |
+
+### Example
+
+```bash
+# Deploy development snapshot
+plesty docs deploy \
+  --remote-url git@gitlab.com:plesty/my-device.git \
+  --target-branch pages
+
+# Deploy a versioned release
+plesty docs deploy \
+  --remote-url git@gitlab.com:plesty/my-device.git \
+  --target-branch pages \
+  --release
+```

plesty_sdk-0.1.0/docs/commands/init.md

@@ -0,0 +1,103 @@
+# plesty init
+
+Initialize a new Plesty project from the official template. The project is created in the
+directory specified by the global `--project-dir` option (defaults to the current working
+directory), making the standard workflow as simple as:
+
+```bash
+mkdir plesty-my-device && cd plesty-my-device
+plesty init device
+```
+
+```bash
+plesty init [PROJECT_TYPE] [OPTIONS]
+```
+
+`PROJECT_TYPE` is one of `device` or `experiment` (default: `default`, not yet available).
+
+## Naming conventions
+
+All Plesty projects follow a consistent naming scheme derived from the module name
+(e.g. `foo_bar`):
+
+| Artifact | Convention | Example |
+|---|---|---|
+| Project folder | `plesty-<kebab-name>` | `plesty-foo-bar` |
+| Source folder | `<module_name>` | `foo_bar` |
+| PyPI distribution | `plesty-<kebab-name>` | `plesty-foo-bar` |
+| Python import | `plesty.<module_name>` | `plesty.foo_bar` |
+
+The `plesty-` prefix in the folder name is automatically stripped when inferring the module
+name, so `plesty-foo-bar` → `foo_bar` without needing `--name`.
+
+## Options
+
+| Option | Default | Description |
+|---|---|---|
+| `--name` | inferred | Python module name — lowercase letters, digits, and `_` only (e.g. `foo_bar`). Inferred from the directory name by stripping the `plesty-` prefix and converting hyphens to underscores. |
+| `--author` | `John Doe` | Author name written into `pyproject.toml` and `spdx.tmpl` |
+| `--email` | `john.doe@example.com` | Author email written into `pyproject.toml` and `spdx.tmpl` |
+| `--ci-stages` | all stages | Comma-separated pipeline stages to include in `.gitlab-ci.yml`. Pass `""` to omit the CI file. |
+
+### Available CI stages
+
+`check`, `test`, `build`, `release`, `deploy`
+
+## Directory rules
+
+- If `--project-dir` does not exist it is created automatically.
+- If it already exists it must be empty (hidden entries such as `.git` are ignored).
+
+## Examples
+
+```bash
+# Minimal: module name inferred from directory, all CI stages, default author
+mkdir plesty-power-meter && cd plesty-power-meter
+plesty init device
+
+# Explicit name and author
+plesty --project-dir ~/projects/plesty-power-meter init device \
+  --name power_meter \
+  --author "Jane Doe" \
+  --email jane@example.com
+
+# Only include check and build stages in CI
+plesty --project-dir ~/projects/plesty-scan-exp init experiment \
+  --name scan_exp \
+  --ci-stages "check,build"
+
+# Skip CI file entirely
+plesty --project-dir ~/projects/plesty-internal-tool init device \
+  --name internal_tool \
+  --ci-stages ""
+```
+
+## Generated project layout
+
+```
+plesty-foo-bar/
+├── foo_bar/
+│   ├── __init__.py
+│   └── __main__.py
+│   └── base_device.py       # device only
+│   └── device.py            # device only
+├── docs/
+│   └── index.md
+├── .gitlab-ci.yml           # omitted when --ci-stages ""
+├── .gitignore
+├── COPYING
+├── LICENSE
+├── LICENSES/
+├── pyproject.toml
+├── README.md
+└── spdx.tmpl
+```
+
+The `pyproject.toml` is pre-configured with:
+- The PyPI distribution name `plesty-foo-bar` (kebab-case, no project-type suffix)
+- A hatchling sources mapping so the package installs under the `plesty` namespace (`import plesty.foo_bar`)
+- Dynamic versioning via `versioningit`
+- `plesty-lib` as a dependency
+- Sphinx docs settings under `[tool.plesty.docs]`
+
+Use `plesty update` to change author info, the PyPI name, or CI stages after initialisation.

plesty_sdk-0.1.0/docs/commands/license.md

@@ -0,0 +1,42 @@
+# plesty license
+
+Manage SPDX license headers across a project's Python source files.
+
+## update
+
+```bash
+plesty license update
+```
+
+Reads author and maintainer metadata from the project's `pyproject.toml`, updates the
+`spdx.tmpl` template in the project root, and applies LGPL-3.0 license headers to every
+`.py` file using [licenseheaders](https://github.com/johann-petrak/licenseheaders).
+
+The following directories are excluded automatically: `.venv`, `build`, `dist`, `.git`.
+
+### Prerequisites
+
+A `spdx.tmpl` file must exist in the project root. It is generated automatically by
+`plesty init`, but you can also create one manually.
+
+The `pyproject.toml` must contain at least one entry in `[project].authors` (with `name`
+and `email`) and one entry in `[project].maintainers` (with `name`).
+
+### Example
+
+```toml
+# pyproject.toml
+[project]
+authors = [{ name = "Jane Doe", email = "jane@example.com" }]
+maintainers = [{ name = "Jane Doe" }]
+```
+
+```bash
+plesty license update
+```
+
+To update headers in a project outside the current directory:
+
+```bash
+plesty --project-dir ../my-device license update
+```

plesty_sdk-0.1.0/docs/commands/manual.md

@@ -0,0 +1,77 @@
+# plesty manual
+
+Generate reference manuals from an external device package's `DocDevice` class.
+
+## generate
+
+```bash
+plesty manual generate [--module-name MODULE] [--output-dir PATH] [--with-pdf]
+```
+
+Imports the device package from the project directory set via `--project-dir` (defaults to
+the current working directory), instantiates its `DocDevice` (or `Device` as a fallback),
+and calls `.summary()` to produce Markdown reference files. Optionally renders PDF versions
+using [md2pdf](https://github.com/jmaupetit/md2pdf).
+
+```{note}
+PDF generation requires the `libpango` system library (a dependency of `weasyprint`/`md2pdf`).
+Install it via your system package manager before using `--with-pdf`:
+`brew install pango` on macOS, `apt install libpango-1.0-0` on Debian/Ubuntu.
+```
+
+### Options
+
+| Option | Default | Description |
+|---|---|---|
+| `--module-name` | inferred | Python module that exposes `DocDevice`. Defaults to the folder name with `-` replaced by `_` |
+| `--output-dir` | `<project-dir>/manual` | Directory where generated files are written |
+| `--with-pdf` | off | Also render PDF files from the generated Markdown |
+
+### Output files
+
+| File | Layout |
+|---|---|
+| `short.md` / `short.pdf` | Compact parameter list — portrait A4 |
+| `table.md` / `table.pdf` | Full parameter table — landscape A4 |
+
+### Module resolution
+
+The command attempts to import the module in this order:
+
+1. The value of `--module-name` if provided.
+2. The folder name of the project directory with `-` replaced by `_`.
+3. Any module discovered via `__init__.py` files under the project directory.
+
+If the module exposes `DocDevice`, that is used. If only `Device` is found, it is used with
+a warning. The class is instantiated automatically if needed.
+
+### Examples
+
+```bash
+# Generate Markdown manuals (run from inside the device project)
+cd ../ape-pulse-slicer
+plesty manual generate
+
+# Or point directly at the project directory
+plesty --project-dir ../ape-pulse-slicer manual generate
+
+# Generate with PDF output
+plesty --project-dir ../ape-pulse-slicer manual generate --with-pdf
+
+# Override the inferred module name and output directory
+plesty --project-dir ../ape-pulse-slicer manual generate \
+  --module-name ape_pulse_slicer.doc \
+  --output-dir ./manuals
+```
+
+### DocDevice interface
+
+The device class must expose a `summary` method with the following signature:
+
+```python
+def summary(self, *, style: str, filename: str) -> None:
+    ...
+```
+
+`style` is either `"short"` or `"md"`. The method should write the generated Markdown to
+`filename`.

plesty_sdk-0.1.0/docs/commands/update.md

@@ -0,0 +1,58 @@
+# plesty update
+
+Update metadata in an existing Plesty project. Only the options you provide are changed;
+everything else is left as-is.
+
+```bash
+plesty update [OPTIONS]
+```
+
+Operates on the directory set by the global `--project-dir` option (defaults to the current
+working directory).
+
+## Options
+
+| Option | Description |
+|---|---|
+| `--author TEXT` | New author name — updates `[project].authors[0].name` in `pyproject.toml` and `Author:` in `spdx.tmpl` |
+| `--email TEXT` | New author email — updates `[project].authors[0].email` in `pyproject.toml` and `Email:` in `spdx.tmpl` |
+| `--name NAME` | New PyPI distribution name — updates `[project].name` in `pyproject.toml` |
+| `--ci-stages STAGES` | Comma-separated pipeline stages — regenerates `.gitlab-ci.yml`. Pass `""` to remove the CI file. |
+
+At least one option must be provided.
+
+### Available CI stages
+
+`check`, `test`, `build`, `release`, `deploy`
+
+## Examples
+
+```bash
+# Change author and email
+plesty update --author "Jane Doe" --email jane@example.com
+
+# Rename the PyPI distribution
+plesty update --name plesty-pm100d-device
+
+# Narrow the CI pipeline to check + build only
+plesty update --ci-stages "check,build"
+
+# Remove the CI file
+plesty update --ci-stages ""
+
+# Combine multiple updates in one call
+plesty update --author "Jane Doe" --email jane@example.com --ci-stages "check,build,release"
+
+# Update a project in another directory
+plesty --project-dir ../plesty-power_meter-device update --author "Jane Doe"
+```
+
+## Notes
+
+- `--author` / `--email` update `pyproject.toml` and `spdx.tmpl` but do **not** re-apply
+  SPDX headers to source files. Run `plesty license update` afterwards to propagate the new
+  identity into all `.py` file headers.
+- `--name` changes only `[project].name`. The Python package directory name and all import
+  paths in source files are left unchanged.
+- `--ci-stages` fully regenerates `.gitlab-ci.yml` from scratch; any manual edits to that
+  file will be lost.

plesty_sdk-0.1.0/docs/getting-started.md

@@ -0,0 +1,90 @@
+# 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 `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`), and documentation
+stubs. 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 **Pixel** level. Add `--standard nebula` or
+`--standard quantum` to raise the bar. 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
+
+When ready to publish, push the built documentation to your remote pages branch:
+
+```bash
+plesty docs deploy --remote-url git@gitlab.com:org/my-device.git --target-branch pages
+```
+
+Use `--release` to tag it as a versioned release instead of the development snapshot.

plesty_sdk-0.1.0/docs/index.md

@@ -0,0 +1,37 @@
+# plesty-sdk
+
+**plesty-sdk** is the official command-line tool for developing Python modules that comply with
+the Plesty standard. It provides tools for enforcing code hygiene, managing documentation,
+applying license headers, scaffolding new projects, and generating device manuals.
+
+## Installation
+
+```bash
+pip install plesty-sdk
+```
+
+After installation, the `plesty` command is available in your environment.
+
+## The `--project-dir` option
+
+All `plesty` commands operate on a Python project directory. By default this is the current
+working directory, but you can point to any directory using the global `--project-dir` (`-d`)
+option:
+
+```bash
+plesty --project-dir /path/to/my-project check
+plesty -d ../my-device docs serve
+```
+
+Every command reads `pyproject.toml`, the `.plesty` cache, and all source paths relative to
+this directory.
+
+## Commands at a glance
+
+| Command | Description |
+|---|---|
+| [`plesty check`](commands/check.md) | Validate a project against a Plesty compliance level |
+| [`plesty build`](commands/build.md) | Scaffold new device or experiment projects from templates |
+| [`plesty docs`](commands/docs.md) | Serve or deploy the project documentation |
+| [`plesty license`](commands/license.md) | Apply and sync SPDX license headers |
+| [`plesty manual`](commands/manual.md) | Generate Markdown/PDF manuals from a device's `DocDevice` |

plesty_sdk-0.1.0/docs/toc.yaml

@@ -0,0 +1,4 @@
+root: index.md
+entries:
+- file: getting-started.md
+- glob: commands/*

plesty_sdk-0.1.0/plesty_sdk/assets/gitlab-ci.yml

@@ -0,0 +1,41 @@
+stages:
+  - check
+  - test
+  - build
+  - release
+  - deploy
+
+variables:
+  # Required for versioningit: the runner must fetch full Git history and tags.
+  GIT_DEPTH: "0"
+
+include:
+  # Check compliance with Plesty standard
+  - component: $CI_SERVER_FQDN/plesty/plesty-ci/check-compliance@main
+    inputs:
+      stage: check
+
+  # Run pytest with coverage reporting
+  - component: $CI_SERVER_FQDN/plesty/plesty-ci/run-tests@main
+    inputs:
+      stage: test
+      job_name: run-tests
+
+  # Build Python package and expose dist/ as an artifact
+  - component: $CI_SERVER_FQDN/plesty/plesty-ci/build-pkg@main
+    inputs:
+      stage: build
+      job_name: build-pkg
+
+  # Publish package to PyPI on release tags
+  - component: $CI_SERVER_FQDN/plesty/plesty-ci/publish-pypi@main
+    inputs:
+      stage: release
+      pypi_token: $PYPI_TOKEN
+      build_job_name: build-pkg
+
+  # Deploy documentation to dedicated documentation branch
+  - component: $CI_SERVER_FQDN/plesty/plesty-ci/deploy-docs@main
+    inputs:
+      stage: deploy
+      access_token: $CI_BOT_TOKEN