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

plestysdk/commands/docs/__init__.py

@@ -0,0 +1,35 @@
+"""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

@@ -0,0 +1,193 @@
+"""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

@@ -0,0 +1,80 @@
+"""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

@@ -0,0 +1,158 @@
+"""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

@@ -0,0 +1,116 @@
+"""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."""