plesty-sdk 0.0.2.dev2__py3-none-any.whl → 0.0.2.dev4__py3-none-any.whl

{plesty_sdk-0.0.2.dev2.dist-info → plesty_sdk-0.0.2.dev4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plesty-sdk
-Version: 0.0.2.dev2
+Version: 0.0.2.dev4
 Summary: Command-line application for developing Python modules compliant with the Plesty standard.
 Author: Plesty Development Team
 License-File: COPYING
@@ -55,5 +55,6 @@ The suggested levels of plesty standards are:
 
 
 ## LICENSE
+
 Plesty is licensed under the GNU Lesser General Public License v3.0 or later
 (LGPL-3.0-or-later). See the LICENSE file.

plesty_sdk-0.0.2.dev4.dist-info/RECORD

@@ -0,0 +1,7 @@
+plesty_sdk-0.0.2.dev4.dist-info/METADATA,sha256=8fy0ilYqdc0rnS2KVAi0k5Xtuez9kz-3nWY-fpwsh8E,2002
+plesty_sdk-0.0.2.dev4.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+plesty_sdk-0.0.2.dev4.dist-info/entry_points.txt,sha256=fNrx7o8Sf1lQfZJM-_uPYcPWbJMO94RAYh7z-DnGB5o,45
+plesty_sdk-0.0.2.dev4.dist-info/licenses/COPYING,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+plesty_sdk-0.0.2.dev4.dist-info/licenses/COPYING.LESSER,sha256=46mU2C5kSwOnkqkw9XQAJlhBL2JAf1_uCD8lVcXyMRg,7652
+plesty_sdk-0.0.2.dev4.dist-info/licenses/LICENSE,sha256=46mU2C5kSwOnkqkw9XQAJlhBL2JAf1_uCD8lVcXyMRg,7652
+plesty_sdk-0.0.2.dev4.dist-info/RECORD,,

plesty_sdk-0.0.2.dev2.dist-info/RECORD

@@ -1,20 +0,0 @@
-plestysdk/__init__.py,sha256=m6UekKftTahNJ3W5K3mZSz4Y4ZZpHRxF_ZAxuaKYL7o,12
-plestysdk/cache.py,sha256=EvqvGCj00oQEzoKij7LyfIX0Her_U9nrezChkZ-u7EQ,3878
-plestysdk/cli.py,sha256=6IY-PvABpDxdl4f79QcvxdvzgErQByNv8acYlaj87ts,1123
-plestysdk/context.py,sha256=4OR7gXMMTG9mbs_yvEj365du23VtuVqbgDQmA_85ENA,5017
-plestysdk/assets/docs-build-gitlab-ci.yml,sha256=Ee-Iu1FymeGc7H93tVdBA-y5vJYNfCur4GVfEYNYd5s,185
-plestysdk/assets/ruff.toml,sha256=aluT6IyKKC66_Z8X4OCQ9ujE1-Cf_mrnVCWCoHMZFMM,222
-plestysdk/assets/logos/plesty_icon.png,sha256=yFrk2tQDGUzTTzRLdsbqUYwhe2YYa7VlXXfzZCUlIrk,18048
-plestysdk/assets/logos/plesty_logo.png,sha256=QgqgLl3s8s-NmrtjTHG650uCzJwblwHwI62nc5IG1bg,15218
-plestysdk/commands/check.py,sha256=xf_mVnece_KaGpmkJ_6oFXk9cdLPhayguSq7Ijp8zwk,5863
-plestysdk/commands/docs/__init__.py,sha256=R7SMCSGhQrm8UM5GqscqdhdjTOmYoP-Zt3MlP7pctkY,1380
-plestysdk/commands/docs/deploy.py,sha256=MJX97wKJKRJEn8_Ovj74Sr9VIirvZxfkyB5cuMjoB5c,8020
-plestysdk/commands/docs/serve.py,sha256=U_6CUtmZFoK3joWBD4maLyX-pDEn4o9ont3ae7SW8ds,2796
-plestysdk/commands/docs/sphinx_builder.py,sha256=DK1w8LAS36V5iKwz8JhSR15qGoecffF99djnutejofo,5392
-plesty_sdk-0.0.2.dev2.dist-info/METADATA,sha256=ocYElNE8o7bPko2QWYHRpK_Ux7GD_8k5Mm7oCNblWUM,2001
-plesty_sdk-0.0.2.dev2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-plesty_sdk-0.0.2.dev2.dist-info/entry_points.txt,sha256=fNrx7o8Sf1lQfZJM-_uPYcPWbJMO94RAYh7z-DnGB5o,45
-plesty_sdk-0.0.2.dev2.dist-info/licenses/COPYING,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-plesty_sdk-0.0.2.dev2.dist-info/licenses/COPYING.LESSER,sha256=46mU2C5kSwOnkqkw9XQAJlhBL2JAf1_uCD8lVcXyMRg,7652
-plesty_sdk-0.0.2.dev2.dist-info/licenses/LICENSE,sha256=46mU2C5kSwOnkqkw9XQAJlhBL2JAf1_uCD8lVcXyMRg,7652
-plesty_sdk-0.0.2.dev2.dist-info/RECORD,,

plestysdk/__init__.py

@@ -1 +0,0 @@
-"""Init."""

plestysdk/assets/docs-build-gitlab-ci.yml

@@ -1,11 +0,0 @@
-stages: [deploy]
-
-pages:
-  stage: deploy
-  rules:
-    - exists:
-      - "html/latest/"
-  script:
-    - echo "Serving documentation on GitLab pages..."
-  pages:
-    publish: html/latest

plestysdk/assets/ruff.toml

@@ -1,11 +0,0 @@
-line-length = 99
-src = ["src"]
-
-[lint]
-# errors, pyflake, warnings, docstring (pydocstyle)
-select = ["E", "F", "W", "D"]
-# as before in the script
-ignore = ["E203", "D401", "D205"]
-
-[lint.pydocstyle]
-convention = "google"

plestysdk/cache.py

@@ -1,106 +0,0 @@
-"""Cache management."""
-
-# Copyright (C) 2025, 2026 Christopher Borchers, fvrehlinger, Maximilian
-# Heller, Michael Zopf (names in alphabetic order wrt. surnames)
-#
-# This file is part of plesty-sdk which is part of the Plesty library.
-#
-# plesty-sdk is free software: you can redistribute it and/or modify it under
-# the terms of the GNU Lesser General Public License as published by the Free
-# Software Foundation, either version 3 of the License, or (at your option) any
-# later version.
-#
-# plesty-sdk is distributed in the hope that it will be useful, but WITHOUT ANY
-# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-# PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public License along
-# with plesty-sdk. If not, see <https://www.gnu.org/licenses/>.
-
-from __future__ import annotations
-import os
-import shutil
-from collections.abc import Callable
-from importlib import metadata
-from typing import ClassVar
-
-
-class CachedFile:
-    """Function decorator for defining cached (text) files with content generated at runtime.
-    This class also serves as a registry of files to be cached.
-    """
-
-    registry: ClassVar[list[CachedFile]] = []
-    """Registry of instanciated CachedFile objects."""
-    filename: str
-    """The path to the file to be cached, relative to the '.plesty' cache directory."""
-    content: Callable[[], str]
-    """The decorated function that generates the content of the cached file."""
-
-    def __init__(self, filename: str) -> None:
-        """Add the File object to the registry.
-
-        Args:
-            filename: The path to the file to be cached, relative to the '.plesty'
-                cache directory.
-        """
-        self.filename = filename
-        CachedFile.registry.append(self)
-
-    def __call__(self, content: Callable[[], str]) -> None:
-        """Apply the decorator to a function."""
-        self.content = content
-
-    def generate(self) -> None:
-        """Write the content of the cached file to disk."""
-        complete_file_path = os.path.join(os.getcwd(), '.plesty', self.filename)
-        os.makedirs(os.path.dirname(complete_file_path), exist_ok=True)
-        with open(complete_file_path, 'xt') as file:
-            file.write(self.content())
-
-    def is_correct(self) -> bool:
-        """Check whether the cached file is up-to-date by comparing the generated content
-        with the content of the existing file on disk.
-
-        Returns:
-            False, if the file does not exist on disk or its content is not up-to-date.
-            True otherwise.
-        """
-        complete_file_path = os.path.join(os.getcwd(), '.plesty', self.filename)
-        if not os.path.exists(complete_file_path):
-            return False
-        with open(complete_file_path, 'rt') as file:
-            existing_content = file.read()
-        if not existing_content == self.content():
-            return False
-        return True
-
-
-def ensure_cache() -> None:
-    """Ensure that the cache directory '.plesty' exists and that all files are
-    up-to-date. If not, (re)create the cache.
-    """
-    for file in CachedFile.registry:
-        if not file.is_correct():
-            break
-    else:
-        return
-
-    cache_dir_path = os.path.join(os.getcwd(), '.plesty')
-    if os.path.exists(cache_dir_path):
-        shutil.rmtree(cache_dir_path)
-    os.makedirs(cache_dir_path)
-    for file in CachedFile.registry:
-        file.generate()
-
-
-@CachedFile('.gitignore')
-def gitignore() -> str:
-    """This file causes the entire '.plesty' cache directory to be ignored by version control."""
-    return '*'
-
-
-@CachedFile('.sdk-version')
-def sdk_version() -> str:
-    """This file specifies the version number of the Plesty SDK used when creating the cache."""
-    return metadata.version('plesty-sdk')

plestysdk/cli.py

@@ -1,32 +0,0 @@
-"""CLI tool."""
-
-# Copyright (C) 2025, 2026 Christopher Borchers, fvrehlinger, Maximilian
-# Heller, Michael Zopf (names in alphabetic order wrt. surnames)
-#
-# This file is part of plesty-sdk which is part of the Plesty library.
-#
-# plesty-sdk is free software: you can redistribute it and/or modify it under
-# the terms of the GNU Lesser General Public License as published by the Free
-# Software Foundation, either version 3 of the License, or (at your option) any
-# later version.
-#
-# plesty-sdk is distributed in the hope that it will be useful, but WITHOUT ANY
-# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-# PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public License along
-# with plesty-sdk. If not, see <https://www.gnu.org/licenses/>.
-
-import click
-
-from plesty_sdk.commands.check import check_command
-from plesty_sdk.commands.docs import docs_command
-
-
-@click.group("plesty")
-def app():
-    """The Plesty CLI tool."""
-
-
-app.add_command(check_command)
-app.add_command(docs_command)

plestysdk/commands/check.py

@@ -1,146 +0,0 @@
-"""Check a module for plesty standard."""
-
-# Copyright (C) 2025, 2026 Christopher Borchers, fvrehlinger, Maximilian
-# Heller, Michael Zopf (names in alphabetic order wrt. surnames)
-#
-# This file is part of plesty-sdk which is part of the Plesty library.
-#
-# plesty-sdk is free software: you can redistribute it and/or modify it under
-# the terms of the GNU Lesser General Public License as published by the Free
-# Software Foundation, either version 3 of the License, or (at your option) any
-# later version.
-#
-# plesty-sdk is distributed in the hope that it will be useful, but WITHOUT ANY
-# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-# PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public License along
-# with plesty-sdk. If not, see <https://www.gnu.org/licenses/>.
-
-import asyncio
-import importlib
-import subprocess
-from importlib import resources
-from pathlib import Path
-from typing import Any, Literal
-
-import click
-from bluesky.protocols import Readable
-try:
-    from PySide6.QtWidgets import QWidget
-    PYSIDE6_IS_INSTALLED = True
-except ImportError:
-    PYSIDE6_IS_INSTALLED = False
-
-from plesty_sdk.context import ApplicationContext, pass_context
-
-
-@click.command(name="check", short_help="Check compliance with the Plesty standard.")
-@click.option(
-    "--standard",
-    help="...",
-    default="pixel",
-    type=click.Choice(["pixel", "nebula", "quantum"]),
-    show_choices=True,
-    show_default=True,
-)
-@click.option("--device", help="...", is_flag=True)
-@pass_context
-def check_command(
-    context: ApplicationContext, standard: Literal["pixel", "nebula", "quantum"], device: bool
-):
-    """..."""
-    # ruff
-    run_linter()
-
-    check_gui(standard, context.pyproject_toml)
-
-    if device:
-        check_device(standard, context.pyproject_toml)
-
-
-def check_gui(standard: Literal["pixel", "nebula", "quantum"], pyproject_toml: dict[str, Any]):
-    """Checks whether the module's GUI class, if present, is compatible with the standard."""
-    click.echo("Checking GUI requirements...")
-    project_name: str = pyproject_toml["project"]["name"]
-    module = importlib.import_module(project_name.replace("-", "_"))
-    try:
-        gui_class = getattr(module, "GUI")
-    except AttributeError:
-        click.echo("Module does not implement a GUI.")
-        return
-    match standard:
-        case "pixel":
-            click.echo("Check passed, no GUI specific requirements in standard pixel.")
-        case "nebula" | "quantum":
-            if not PYSIDE6_IS_INSTALLED:
-                raise click.ClickException(
-                    "PySide6 is not installed in the environment, but the GUI "
-                    "class is required to inherit from PySide6.QtWidgets.QtWidget "
-                    f"to be compatible with plesty standard {standard}."
-                )
-            if not issubclass(gui_class, QWidget):
-                raise click.ClickException(
-                    "GUI class does not inherit from PySide6.QtWidgets.QtWidget "
-                    f"required by plesty standard {standard}."
-                )
-            try:
-                if not callable(getattr(gui_class, "connect")):
-                    raise AttributeError
-            except AttributeError:
-                raise click.ClickException(
-                    "GUI class does not implement a connect method "
-                    f"required by plesty standard {standard}."
-                )
-            click.echo(f"Check passed for standard {standard}.")
-
-
-def check_device(standard: Literal["pixel", "nebula", "quantum"], pyproject_toml: dict[str, Any]):
-    """Checks whether the device has a Bluesky compatible interface."""
-    click.echo("Checking device specific requirements...")
-    match standard:
-        case "pixel":
-            click.echo("Check passed, no device specific requirements in standard pixel.")
-        case "nebula" | "quantum":
-            device_class = pyproject_toml["tool"]["plesty"]["device-class"]
-            project_name = pyproject_toml["project"]["name"]
-            module = importlib.import_module(project_name.replace("-", "_"))
-            device_instance = getattr(module, device_class)()
-            # check for compatibility with bluesky Readable
-            if not isinstance(device_instance, Readable):
-                raise click.ClickException(
-                    "Device class does not implement the 'Readable' protocol from Bluesky required"
-                    f"by standard {standard}."
-                )
-            # check for async connect method
-            if not asyncio.iscoroutinefunction(getattr(device_instance, "connect")):
-                raise click.ClickException(
-                    "Device class does not implement an asyncronous 'connect' functions requried"
-                    f"by plesty standard {standard}."
-                )
-            click.echo(f"Check passed for standard {standard}.")
-
-
-def run_linter():
-    """Run ruff linter.
-
-    Prints errors if checks are not fulfilled and exits.
-    Checks pyflakes, pycodestyle errors & warnings and pydocstyle.
-    Independent of standard level, as it needs to be fulfilled for every level.
-    """
-    pkg_root = resources.files("plesty_sdk")
-    config = pkg_root.joinpath("assets/ruff.toml")
-
-    repo_root = str(Path.cwd())
-    with resources.as_file(config) as config_path:
-        commands = [
-            ["ruff", "check", "--config", str(config_path), repo_root],
-            ["ruff", "format", "--check", "--config", str(config_path), repo_root],
-        ]
-
-        for cmd in commands:
-            p = subprocess.run(cmd, text=True, capture_output=True)
-            print(p.stdout)
-            print(p.stderr)
-            if p.returncode != 0:
-                raise SystemExit(p.returncode)

plestysdk/commands/docs/__init__.py

@@ -1,35 +0,0 @@
-"""CLI commands for previewing and deploying Sphinx documentation pages."""
-
-# Copyright (C) 2025, 2026 Christopher Borchers, fvrehlinger, Maximilian
-# Heller, Michael Zopf (names in alphabetic order wrt. surnames)
-#
-# This file is part of plesty-sdk which is part of the Plesty library.
-#
-# plesty-sdk is free software: you can redistribute it and/or modify it under
-# the terms of the GNU Lesser General Public License as published by the Free
-# Software Foundation, either version 3 of the License, or (at your option) any
-# later version.
-#
-# plesty-sdk is distributed in the hope that it will be useful, but WITHOUT ANY
-# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-# PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public License along
-# with plesty-sdk. If not, see <https://www.gnu.org/licenses/>.
-
-import click
-
-from plesty_sdk.commands.docs.deploy import deploy_command
-from plesty_sdk.commands.docs.serve import serve_command
-from plesty_sdk.context import ApplicationContext, pass_context
-
-
-@click.group('docs')
-@pass_context
-def docs_command(context: ApplicationContext):
-    """Preview and deploy documentation pages."""
-    context.ensure_docs_index()
-
-
-docs_command.add_command(deploy_command)
-docs_command.add_command(serve_command)

plestysdk/commands/docs/deploy.py

@@ -1,193 +0,0 @@
-"""The plesty docs deploy command."""
-
-# Copyright (C) 2025, 2026 Christopher Borchers, fvrehlinger, Maximilian
-# Heller, Michael Zopf (names in alphabetic order wrt. surnames)
-#
-# This file is part of plesty-sdk which is part of the Plesty library.
-#
-# plesty-sdk is free software: you can redistribute it and/or modify it under
-# the terms of the GNU Lesser General Public License as published by the Free
-# Software Foundation, either version 3 of the License, or (at your option) any
-# later version.
-#
-# plesty-sdk is distributed in the hope that it will be useful, but WITHOUT ANY
-# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-# PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public License along
-# with plesty-sdk. If not, see <https://www.gnu.org/licenses/>.
-
-import contextlib
-import json
-import os
-import shutil
-import subprocess
-from importlib import metadata, resources
-from packaging.version import InvalidVersion, Version
-from tempfile import TemporaryDirectory
-
-import click
-
-from plesty_sdk.commands.docs.sphinx_builder import build_sphinx_app
-from plesty_sdk.context import ApplicationContext, pass_context
-
-
-@click.command(
-    name='deploy', short_help="Build and push documentation pages to a remote branch."
-)
-@click.argument('remote_url', required=True)
-@click.argument('target_branch', required=True)
-@click.option(
-    "--release/--latest",
-    is_flag=True,
-    required=True,
-    help="Whether to deploy the documentation pages for a "
-         "release version or the latest development version.",
-)
-@pass_context
-def deploy_command(
-    context: ApplicationContext, remote_url: str, target_branch: str, release: bool
-):
-    """Build and push the documentation pages for the Plesty project in the
-    current working directory to the <TARGET_BRANCH> of the repository at
-    <REMOTE_URL>. The branch is created if it does not yet exist.
-    """
-    if release:
-        try:
-            version_str = metadata.version(context.pyproject_toml['project']['name'])
-        except metadata.PackageNotFoundError:
-            try:
-                version_str = context.pyproject_toml['project']['version']
-            except KeyError:
-                raise click.ClickException(
-                    "The project version could not be retrieved either from the build "
-                    "metadata - as the project is not installed in the current "
-                    "environment - or directly from the pyproject.toml file."
-                )
-        try:
-            version = Version(version_str)
-        except InvalidVersion:
-            raise click.ClickException("The project version is not PEP 440 compliant.")
-        version_tag = f'{version.major}.{version.minor}'
-        build_dir = os.path.join('html', 'releases', version_tag)
-    else:
-        version_tag = None
-        build_dir = os.path.join('html', 'latest')
-
-    with TemporaryDirectory() as tmp_dir:
-        with contextlib.chdir(tmp_dir):
-            # check whether target branch exists on remote
-            if run_git(
-                ['ls-remote', '--exit-code', '--heads', remote_url, target_branch],
-                expected_exit_codes={0, 2}
-            ) == 0:
-                click.echo(f"Branch {target_branch} exists on remote. Cloning...")
-                run_git(['clone', '--branch', target_branch, '--depth', '1', remote_url, '.'])
-            else:
-                click.echo(
-                    f"Branch {target_branch} does not yet exist "
-                    "on remote. Creating orphan branch..."
-                )
-                run_git(['init'])
-                run_git(['checkout', '--orphan', target_branch])
-                with resources.as_file(
-                    resources.files('plesty_sdk').joinpath('assets', 'docs-build-gitlab-ci.yml')
-                ) as gitlab_ci_yml:
-                    shutil.copyfile(gitlab_ci_yml, os.path.join(tmp_dir, '.gitlab-ci.yml'))
-                run_git(['add', '.gitlab-ci.yml'])
-                run_git(['commit', '--message', 'Initialize documentation branch.'])
-
-        click.echo("Building documentation...")
-        build_sphinx_app(
-            context.docs_settings,
-            version_tag,
-            build_dir=os.path.join(tmp_dir, build_dir),
-            delete_artifacts=True,
-        )
-        if version_tag is not None:
-            update_versions_json(os.path.join(tmp_dir, 'html', 'releases'), version_tag)
-
-        with contextlib.chdir(tmp_dir):
-            click.echo("Analyzing changes...")
-            run_git(['add', '--all'])
-            if run_git(['diff', '--staged', '--quiet'], expected_exit_codes={0, 1}) == 0:
-                click.echo("No changes made to the documentation pages.")
-            else:
-                commit_message = (
-                    f"Add or update documentation pages for version {version_tag}."
-                ) if version_tag is not None else "Update latest documentation pages."
-                run_git(['commit', '--message', commit_message])
-                run_git(['push', remote_url, target_branch])
-                click.echo("Changes to the documentation pages successfully pushed.")
-
-
-def run_git(args: list[str], expected_exit_codes: set[int] = {0}) -> int:
-    """Run a git command in the current working directory.
-
-    Args:
-        args: The arguments and flags to be passed to the git command.
-        expected_exit_codes: Exit codes that should not raise an exception.
-
-    Returns:
-        The exit code of the git command.
-
-    Raises:
-        click.ClickException: If the exit code is not in `expected_exit_codes`.
-    """
-    if shutil.which('git') is None:
-        raise click.ClickException("Git is not installed or not found in PATH.")
-    result = subprocess.run((command := ['git'] + args), capture_output=True)
-    if result.returncode in expected_exit_codes:
-        return result.returncode
-    else:
-        error_message = result.stderr.decode('utf-8', errors='replace')
-        raise click.ClickException(f"Failed to run {' '.join(command)}.\n{error_message}")
-
-
-def version_tuple(version_tag: str) -> tuple[int, int]:
-        """Parse a version tag into a tuple of the form (major, minor).
-
-        Args:
-            version_tag: The version tag to be parsed in 'major.minor' format.
-
-        Returns:
-            Version tuple of the form (major, minor) as integers.
-        """
-        major, minor = version_tag.split('.')
-        return (int(major), int(minor))
-
-
-def update_versions_json(releases_dir: str, new_version_tag: str) -> None:
-    """Update the versions.json file to include the newly built version in the correct order
-    without duplicates. If necessary, update the automatic redirection to the newest version.
-
-    Args:
-        releases_dir: The directory containing the versions.json file.
-        new_version_tag: The version tag to be added.
-    """
-    versions_json_path = os.path.join(releases_dir, 'versions.json')
-    try:
-        with open(versions_json_path, 'rt', encoding='utf-8') as file:
-            version_list: list[dict[str, str]] = json.load(file)
-    except FileNotFoundError:
-        version_list = []
-
-    new_version = version_tuple(new_version_tag)
-    new_version_entry = {'version': new_version_tag, 'url': f'/{new_version_tag}/'}
-    i = 0
-    while True:
-        if i == len(version_list):
-            version_list.append(new_version_entry)
-            break
-        old_version = version_tuple(version_list[i]['version'])
-        if new_version == old_version:
-            break
-        if new_version > old_version:
-            version_list.insert(i, new_version_entry)
-            break
-        i += 1
-
-    with open(versions_json_path, 'wt', encoding='utf-8') as file:
-        json.dump(version_list, file, indent=4)
-    with open(os.path.join(releases_dir, 'index.html'), 'wt') as file:
-        file.write(f'<script>window.location.replace("{version_list[0]['url']}")</script>')

plestysdk/commands/docs/serve.py

@@ -1,80 +0,0 @@
-"""The plesty docs serve command."""
-
-# Copyright (C) 2025, 2026 Christopher Borchers, fvrehlinger, Maximilian
-# Heller, Michael Zopf (names in alphabetic order wrt. surnames)
-#
-# This file is part of plesty-sdk which is part of the Plesty library.
-#
-# plesty-sdk is free software: you can redistribute it and/or modify it under
-# the terms of the GNU Lesser General Public License as published by the Free
-# Software Foundation, either version 3 of the License, or (at your option) any
-# later version.
-#
-# plesty-sdk is distributed in the hope that it will be useful, but WITHOUT ANY
-# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-# PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public License along
-# with plesty-sdk. If not, see <https://www.gnu.org/licenses/>.
-
-import logging
-import os
-from threading import Thread
-
-import click
-import livereload
-import watchfiles
-
-from plesty_sdk.cache import ensure_cache
-from plesty_sdk.commands.docs.sphinx_builder import build_sphinx_app
-from plesty_sdk.context import ApplicationContext, pass_context
-
-
-logging.getLogger('livereload').disabled = True
-for name in ['tornado.access', 'tornado.application', 'tornado.general']:
-    logging.getLogger(name).setLevel(logging.CRITICAL)
-
-
-@click.command(
-    name='serve', short_help="Preview the documentation pages using a local webserver."
-)
-@click.option(
-    '--dev-addr',
-    default='localhost:8000',
-    help="IP address and port",
-    show_default=True,
-    metavar="<IP:PORT>",
-)
-@pass_context
-def serve_command(context: ApplicationContext, dev_addr: str):
-    """Start a local development webserver to preview the documentation pages
-    for the Plesty project in the current working directory. Changes to the
-    .md or .rst files are applied immediately via live reload.
-    """
-    ensure_cache()
-    sphinx_app = build_sphinx_app(
-        context.docs_settings,
-        version_tag=None,
-        build_dir=os.path.join('.plesty', 'docs-build'),
-        delete_artifacts=False,
-    )
-
-    def watch_changes():
-        for _ in watchfiles.watch(sphinx_app.srcdir):
-            sphinx_app.build()
-
-    watcher_thread = Thread(target=watch_changes, daemon=True)
-    watcher_thread.start()
-
-    server = livereload.Server()
-    dev_host, dev_port = dev_addr.split(':')
-    click.echo(f"Serving preview at http://{dev_host}:{dev_port}.")
-    click.echo(
-        f"Changes in ./{os.path.relpath(sphinx_app.srcdir)} "
-        "are detected and immediately visible."
-    )
-    click.echo("Press Ctrl+C to stop the server.")
-    server.serve(
-        host=dev_host, port=int(dev_port), root=os.path.join('.plesty', 'docs-build')
-    )
-    click.echo("Server shut down.")

plestysdk/commands/docs/sphinx_builder.py

@@ -1,158 +0,0 @@
-"""Sphinx app configuration and build process."""
-
-# Copyright (C) 2025, 2026 Christopher Borchers, fvrehlinger, Maximilian
-# Heller, Michael Zopf (names in alphabetic order wrt. surnames)
-#
-# This file is part of plesty-sdk which is part of the Plesty library.
-#
-# plesty-sdk is free software: you can redistribute it and/or modify it under
-# the terms of the GNU Lesser General Public License as published by the Free
-# Software Foundation, either version 3 of the License, or (at your option) any
-# later version.
-#
-# plesty-sdk is distributed in the hope that it will be useful, but WITHOUT ANY
-# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-# PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public License along
-# with plesty-sdk. If not, see <https://www.gnu.org/licenses/>.
-
-import os
-import shutil
-from datetime import date
-from importlib import resources
-from typing import Any
-
-from sphinx.application import Sphinx
-
-from plesty_sdk.context import DocumentationSettings
-
-
-def make_sphinx_config(
-    settings: DocumentationSettings, version_tag: str | None, logo_dir: os.PathLike[str]
-) -> dict[str, Any]:
-    """Set up the Sphinx configuration dictionary customized for the project.
-
-    Args:
-        settings: The documentation settings.
-        version_tag: The version for which the documentation pages are built.
-        logo_dir: The directory containing the logo files.
-
-    Returns:
-        The Sphinx configuration dictionary.
-    """
-    config = dict[str, Any](
-        project = settings.site_name,
-        copyright = f"{date.today().year}, Plesty Development Team",
-        extensions = [
-            'myst_parser',
-            'sphinx.ext.autodoc',
-            'sphinx.ext.napoleon',
-            'sphinxcontrib.mermaid',
-            'sphinx_design',
-            'sphinx_copybutton',
-        ],
-        source_suffix = {
-            '.rst': 'restructuredtext',
-            '.md': 'markdown',
-        },
-        # HTML theme
-        html_theme = 'pydata_sphinx_theme',
-        html_theme_options = {
-            'navbar_center': ['navbar-nav'],
-            'secondary_sidebar_items': ['page-toc', 'sourcelink'],
-            'footer_start': ['copyright'],
-            'footer_center': [],
-            'footer_end': ['theme-version'],
-            'logo': {
-                'text': settings.site_name,
-            },
-        },
-        html_sidebars = {
-            '*': [],
-        },
-        html_logo = os.path.join(logo_dir, 'plesty_logo.png'),
-        html_favicon = os.path.join(logo_dir, 'plesty_icon.png'),
-        # MyST configuration
-        myst_enable_extensions = ['colon_fence'],
-        myst_fence_as_directive = ['mermaid'],
-    )
-
-    if version_tag is not None:
-        config['html_theme_options']['navbar_center'].insert(0, 'version-switcher')
-        config['html_theme_options']['switcher'] = {
-            'json_url': '/versions.json',
-            'version_match': version_tag,
-        }
-
-    if settings.api_reference:
-        project_root = os.getcwd()
-        if not os.path.isdir(src_dir := os.path.join(project_root, 'src')):
-            src_dir = project_root
-
-        import_packages = [
-            entry.path for entry in os.scandir(src_dir) if (
-                entry.is_dir()
-                and entry.name != "tests"
-                and os.path.isfile(os.path.join(entry.path, '__init__.py'))
-            )
-        ]
-
-        if import_packages:
-            config['extensions'].append('autoapi.extension')
-            config.update(
-                autoapi_generate_api_docs = True,
-                autoapi_add_toctree_entry = True,
-                autoapi_root = 'reference',
-                autoapi_dirs = import_packages,
-                autoapi_python_class_content = 'both',
-                napoleon_google_docstring = True,
-                autodoc_typehints = 'both',
-           )
-
-    if settings.toc_file is not None:
-        config['extensions'].append('sphinx_external_toc')
-        config.update(
-            suppress_warnings = ["etoc.toctree"],
-            external_toc_path = settings.toc_file,
-        )
-
-    return config
-
-
-def build_sphinx_app(
-    settings: DocumentationSettings,
-    version_tag: str | None,
-    build_dir: str,
-    delete_artifacts: bool,
-) -> Sphinx:
-    """Build the Sphinx application.
-
-    Args:
-        settings: The documentation settings.
-        version_tag: The version for which the documentation pages are built.
-        build_dir: The location where the documentation pages are built.
-        delete_artifacts: Whether to delete Sphinx build artifacts.
-
-    Returns:
-        The Sphinx application object.
-    """
-    if os.path.isdir(build_dir):
-        shutil.rmtree(build_dir)
-
-    with resources.as_file(resources.files('plesty_sdk').joinpath('assets', 'logos')) as logo_dir:
-        app = Sphinx(
-            srcdir=settings.docs_dir,
-            confdir=None,
-            outdir=build_dir,
-            doctreedir=os.path.join(build_dir, '.doctrees'),
-            buildername='html',
-            confoverrides=make_sphinx_config(settings, version_tag, logo_dir),
-        )
-        app.build()
-
-    if delete_artifacts:
-        shutil.rmtree(os.path.join(build_dir, '.doctrees'))
-        os.remove(os.path.join(build_dir, '.buildinfo'))
-
-    return app

plestysdk/context.py

@@ -1,116 +0,0 @@
-"""Cross-command context management."""
-
-# Copyright (C) 2025, 2026 Christopher Borchers, fvrehlinger, Maximilian
-# Heller, Michael Zopf (names in alphabetic order wrt. surnames)
-#
-# This file is part of plesty-sdk which is part of the Plesty library.
-#
-# plesty-sdk is free software: you can redistribute it and/or modify it under
-# the terms of the GNU Lesser General Public License as published by the Free
-# Software Foundation, either version 3 of the License, or (at your option) any
-# later version.
-#
-# plesty-sdk is distributed in the hope that it will be useful, but WITHOUT ANY
-# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-# PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public License along
-# with plesty-sdk. If not, see <https://www.gnu.org/licenses/>.
-
-import os
-import tomllib
-from typing import Any
-
-import click
-
-
-class DocumentationSettings:
-    """Settings for generating the documentation pages,
-    which can be configured in the pyproject.toml file.
-    """
-
-    site_name: str
-    """The title of the website present on each page next to the Plesty logo."""
-    docs_dir: str
-    """The directory containing the .md or .rst files to generate the documentation from."""
-    api_reference: bool
-    """Whether to automatically generate API reference pages."""
-    toc_file: str | None
-    """The path to the external TOC file."""
-
-    def __init__(self, pyproject_toml: dict[str, Any]) -> None:
-        """Read the documentation settings specified by the user in the [tool.plesty.docs]
-        section of the pyproject.toml file and set default values for missing settings.
-
-        Args:
-            pyproject_toml: The parsed content of the pyproject.toml file.
-        """
-        try:
-            plesty_docs_section: dict[str, Any] = pyproject_toml['tool']['plesty']['docs']
-        except KeyError:
-            plesty_docs_section = {}
-
-        self.site_name = plesty_docs_section.get('site-name', pyproject_toml['project']['name'])
-        self.docs_dir = os.path.join(os.getcwd(), plesty_docs_section.get('docs-dir', 'docs'))
-        self.api_reference = plesty_docs_section.get('api-reference', True)
-
-        if (toc_file := plesty_docs_section.get('toc-file', 'toc.yaml')) == '':
-            self.toc_file = None
-        else:
-            self.toc_file = os.path.join(self.docs_dir, toc_file)
-
-
-class ApplicationContext:
-    """Container class for storing data shared across multiple commands."""
-
-    pyproject_toml: dict[str, Any]
-    """The parsed content of the pyproject.toml file in the current working directory."""
-    docs_settings: DocumentationSettings
-    """The documentation settings."""
-
-    def __init__(self) -> None:
-        """Parse the pyproject.toml file and read the documentation settings."""
-        pyproject_toml_path = os.path.join(os.getcwd(), 'pyproject.toml')
-        try:
-            with open(pyproject_toml_path, 'rb') as file:
-                self.pyproject_toml = tomllib.load(file)
-        except FileNotFoundError:
-            raise click.ClickException(
-                "No pyproject.toml file found in the current "
-                f"working directory at {pyproject_toml_path}."
-            )
-
-        self.docs_settings = DocumentationSettings(self.pyproject_toml)
-
-    def ensure_docs_index(self) -> None:
-        """Ensure that the docs directory exists and contains an index.md or index.rst
-        file, as well as the external TOC file, if specified in the documentation settings.
-
-        Raises:
-            click.ClickException: If a required file is missing.
-        """
-        if not os.path.isdir(self.docs_settings.docs_dir):
-            raise click.ClickException(
-                f"No docs directory found at {self.docs_settings.docs_dir}. Create one or ensure "
-                "that the correct docs directory is specified in the pyproject.toml file."
-            )
-        if not (
-            os.path.isfile(os.path.join(self.docs_settings.docs_dir, 'index.md'))
-            or os.path.isfile(os.path.join(self.docs_settings.docs_dir, 'index.rst'))
-        ):
-            raise click.ClickException(
-                "No index.md or index.rst master file found in the docs "
-                "directory (entry point for the documentation generation)."
-            )
-        if not (
-            self.docs_settings.toc_file is None or os.path.isfile(self.docs_settings.toc_file)
-        ):
-            raise click.ClickException(
-                f"No external TOC file found at {self.docs_settings.toc_file}. Create one or "
-                "ensure that the correct path is specified in the pyproject.toml file. If you "
-                "do not want to use an external table of contents, specify an empty string."
-            )
-
-
-pass_context = click.make_pass_decorator(ApplicationContext, ensure=True)
-"""Decorator to pass the application context to a Click command as the first argument."""