edge-containers-cli 5.2.1__tar.gz → 5.3.0a3__tar.gz

{edge_containers_cli-5.2.1 → edge_containers_cli-5.3.0a3}/.copier-answers.yml

@@ -1,5 +1,5 @@
 # Changes here will be overwritten by Copier
-_commit: 5.0.2
+_commit: 5.2.0
 _src_path: gh:DiamondLightSource/python-copier-template
 author_email: giles.knap@gmail.com
 author_name: Giles Knap
@@ -7,7 +7,7 @@ description: CLI for deploying and managing epics containers IOCs and services
 distribution_name: edge-containers-cli
 docker: true
 docker_debug: false
-docs_type: README
+docs_type: sphinx
 git_platform: github.com
 github_org: epics-containers
 package_name: edge_containers_cli

{edge_containers_cli-5.2.1 → edge_containers_cli-5.3.0a3}/.github/CONTRIBUTING.md

@@ -24,4 +24,4 @@ It is recommended that developers use a [vscode devcontainer](https://code.visua
 
 This project was created using the [Diamond Light Source Copier Template](https://github.com/DiamondLightSource/python-copier-template) for Python projects.
 
-For more information on common tasks like setting up a developer environment, running the tests, and setting a pre-commit hook, see the template's [How-to guides](https://diamondlightsource.github.io/python-copier-template/5.0.2/how-to.html).
+For more information on common tasks like setting up a developer environment, running the tests, and setting a pre-commit hook, see the template's [How-to guides](https://diamondlightsource.github.io/python-copier-template/5.2.0/how-to.html).

edge_containers_cli-5.3.0a3/.github/workflows/_docs.yml

@@ -0,0 +1,55 @@
+on:
+  workflow_call:
+
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Avoid git conflicts when tag and branch pushed at same time
+        if: github.ref_type == 'tag'
+        run: sleep 60
+
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          # Need this to get version number from last tag
+          fetch-depth: 0
+
+      - name: Install system packages
+        run: sudo apt-get install graphviz
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Build docs
+        run: uv run --locked tox -e docs
+
+      - name: Remove environment.pickle
+        run: rm build/html/.doctrees/environment.pickle
+
+      - name: Upload built docs artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs
+          path: build
+
+      - name: Sanitize ref name for docs version
+        run: echo "DOCS_VERSION=${GITHUB_REF_NAME//[^A-Za-z0-9._-]/_}" >> $GITHUB_ENV
+
+      - name: Move to versioned directory
+        run: mv build/html .github/pages/$DOCS_VERSION
+
+      - name: Write switcher.json
+        run: python .github/pages/make_switcher.py --add $DOCS_VERSION ${{ github.repository }} .github/pages/switcher.json
+
+      - name: Publish Docs to gh-pages
+        if: github.ref_type == 'tag' || github.ref_name == 'main'
+        # We pin to the SHA, not the tag, for security reasons.
+        # https://docs.github.com/en/actions/learn-github-actions/security-hardening-for-github-actions#using-third-party-actions
+        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: .github/pages
+          keep_files: true

{edge_containers_cli-5.2.1 → edge_containers_cli-5.3.0a3}/.github/workflows/ci.yml

@@ -19,7 +19,7 @@ jobs:
     strategy:
       matrix:
         runs-on: ["ubuntu-latest"] # can add windows-latest, macos-latest
-        python-version: ["3.11", "3.12", "3.13"]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
       fail-fast: false
     uses: ./.github/workflows/_test.yml
     with:
@@ -36,6 +36,11 @@ jobs:
       contents: read
       packages: write
 
+  docs:
+    uses: ./.github/workflows/_docs.yml
+    permissions:
+      contents: write
+
   dist:
     uses: ./.github/workflows/_dist.yml
 
@@ -47,7 +52,7 @@ jobs:
       id-token: write
 
   release:
-    needs: [dist, test]
+    needs: [dist, test, docs]
     if: github.ref_type == 'tag'
     uses: ./.github/workflows/_release.yml
     permissions:

edge_containers_cli-5.3.0a3/.github/workflows/periodic.yml

@@ -0,0 +1,13 @@
+name: Periodic
+
+on:
+  workflow_dispatch:
+  schedule:
+    # Run weekly to check URL links still resolve
+    - cron: "0 8 * * WED"
+
+jobs:
+  linkcheck:
+    uses: ./.github/workflows/_tox.yml
+    with:
+      tox: docs -- -b linkcheck

{edge_containers_cli-5.2.1 → edge_containers_cli-5.3.0a3}/Dockerfile

@@ -1,6 +1,6 @@
 # The devcontainer should use the developer target and run as root with podman
 # or docker with user namespaces.
-FROM ghcr.io/diamondlightsource/ubuntu-devcontainer:noble AS developer
+FROM ghcr.io/diamondlightsource/ubuntu-devcontainer:resolute AS developer
 
 # Add any system dependencies for the developer/build environment here
 RUN apt-get update -y && apt-get install -y --no-install-recommends \
@@ -21,11 +21,11 @@ ENV UV_PYTHON_INSTALL_DIR=/python
 
 # Sync the project without its dev dependencies
 RUN --mount=type=cache,target=/root/.cache/uv \
-    uv sync --locked --no-editable --no-dev
+    uv sync --locked --no-editable --no-dev --managed-python
 
 
 # The runtime stage copies the built venv into a runtime container
-FROM ubuntu:noble AS runtime
+FROM ubuntu:resolute AS runtime
 
 # Add apt-get system dependecies for runtime here if needed
 # RUN apt-get update -y && apt-get install -y --no-install-recommends \

{edge_containers_cli-5.2.1 → edge_containers_cli-5.3.0a3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edge-containers-cli
-Version: 5.2.1
+Version: 5.3.0a3
 Summary: CLI for deploying and managing epics containers IOCs and services
 Author-email: Giles Knap <giles.knap@gmail.com>
 License:                                  Apache License
@@ -211,6 +211,7 @@ Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -242,9 +243,12 @@ For detailed documentation on the framework that this supports see:
 https://epics-containers.github.io/
 
 
-Source          | <https://github.com/epics-containers/edge-containers-cli>
+What            | Where
 :---:           | :---:
+Source          | <https://github.com/epics-containers/edge-containers-cli>
 PyPI            | `pip install edge-containers-cli`
+Docker          | `docker run ghcr.io/epics-containers/edge-containers-cli:latest`
+Documentation   | <https://epics-containers.github.io/edge-containers-cli>
 Releases        | <https://github.com/epics-containers/edge-containers-cli/releases>
 
 
@@ -265,8 +269,12 @@ To demo the TUI as a web application:
 
 Dashboard:
 
-![screenshot](docs/images/ec-web.png)
+![screenshot](https://raw.githubusercontent.com/epics-containers/edge-containers-cli/main/docs/images/ec-web.png)
 
 IOC logs:
 
-![screenshot](docs/images/ec-logs.png)
+![screenshot](https://raw.githubusercontent.com/epics-containers/edge-containers-cli/main/docs/images/ec-logs.png)
+
+<!-- README only content. Anything below this line won't be included in index.md -->
+
+See https://epics-containers.github.io/edge-containers-cli for more detailed documentation.

{edge_containers_cli-5.2.1 → edge_containers_cli-5.3.0a3}/README.md

@@ -16,9 +16,12 @@ For detailed documentation on the framework that this supports see:
 https://epics-containers.github.io/
 
 
-Source          | <https://github.com/epics-containers/edge-containers-cli>
+What            | Where
 :---:           | :---:
+Source          | <https://github.com/epics-containers/edge-containers-cli>
 PyPI            | `pip install edge-containers-cli`
+Docker          | `docker run ghcr.io/epics-containers/edge-containers-cli:latest`
+Documentation   | <https://epics-containers.github.io/edge-containers-cli>
 Releases        | <https://github.com/epics-containers/edge-containers-cli/releases>
 
 
@@ -39,8 +42,12 @@ To demo the TUI as a web application:
 
 Dashboard:
 
-![screenshot](docs/images/ec-web.png)
+![screenshot](https://raw.githubusercontent.com/epics-containers/edge-containers-cli/main/docs/images/ec-web.png)
 
 IOC logs:
 
-![screenshot](docs/images/ec-logs.png)
+![screenshot](https://raw.githubusercontent.com/epics-containers/edge-containers-cli/main/docs/images/ec-logs.png)
+
+<!-- README only content. Anything below this line won't be included in index.md -->
+
+See https://epics-containers.github.io/edge-containers-cli for more detailed documentation.

edge_containers_cli-5.3.0a3/docs/_api.rst

@@ -0,0 +1,16 @@
+:orphan:
+
+..
+   This page is not included in the TOC tree, but must exist so that the
+   autosummary pages are generated for edge_containers_cli and all its
+   subpackages
+
+API
+===
+
+.. autosummary::
+    :toctree: _api
+    :template: custom-module-template.rst
+    :recursive:
+
+    edge_containers_cli

edge_containers_cli-5.3.0a3/docs/_templates/custom-module-template.rst

@@ -0,0 +1,37 @@
+{{ ('``' + fullname + '``') | underline }}
+
+{%- set filtered_members = [] %}
+{%- for item in members %}
+    {%- if item in functions + classes + exceptions + attributes %}
+        {% set _ = filtered_members.append(item) %}
+    {%- endif %}
+{%- endfor %}
+
+.. automodule:: {{ fullname }}
+    :members:
+
+    {% block modules %}
+    {% if modules %}
+    .. rubric:: Submodules
+
+    .. autosummary::
+        :toctree:
+        :template: custom-module-template.rst
+        :recursive:
+    {% for item in modules %}
+        {{ item }}
+    {%- endfor %}
+    {% endif %}
+    {% endblock %}
+
+    {% block members %}
+    {% if filtered_members %}
+    .. rubric:: Members
+
+    .. autosummary::
+        :nosignatures:
+    {% for item in filtered_members %}
+        {{ item }}
+    {%- endfor %}
+    {% endif %}
+    {% endblock %}

{edge_containers_cli-5.2.1 → edge_containers_cli-5.3.0a3}/docs/conf.py

@@ -1,8 +1,9 @@
-# Configuration file for the Sphinx documentation builder.
-#
-# This file only contains a selection of the most common options. For a full
-# list see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
+"""Configuration file for the Sphinx documentation builder.
+
+This file only contains a selection of the most common options. For a full
+list see the documentation:
+https://www.sphinx-doc.org/en/master/usage/configuration.html
+"""
 
 import sys
 from pathlib import Path
@@ -32,6 +33,8 @@ else:
 extensions = [
     # Use this for generating API docs
     "sphinx.ext.autodoc",
+    # and making summary tables at the top of API docs
+    "sphinx.ext.autosummary",
     # This can parse google style docstrings
     "sphinx.ext.napoleon",
     # For linking to external sphinx documentation
@@ -44,8 +47,13 @@ extensions = [
     "sphinx_copybutton",
     # For the card element
     "sphinx_design",
+    # So we can write markdown files
+    "myst_parser",
 ]
 
+# So we can use the ::: syntax
+myst_enable_extensions = ["colon_fence"]
+
 # If true, Sphinx will warn about all references where the target cannot
 # be found.
 nitpicky = True
@@ -75,6 +83,12 @@ autodoc_member_order = "bysource"
 # Don't inherit docstrings from baseclasses
 autodoc_inherit_docstrings = False
 
+# Document only what is in __all__
+autosummary_ignore_module_all = False
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
 # Output graphviz directive produced images in a scalable format
 graphviz_output_format = "svg"
 
@@ -82,9 +96,6 @@ graphviz_output_format = "svg"
 # role, that is, for text marked up `like this`
 default_role = "any"
 
-# The suffix of source filenames.
-source_suffix = ".rst"
-
 # The master toctree document.
 master_doc = "index"
 
@@ -103,15 +114,6 @@ intersphinx_mapping = {"python": ("https://docs.python.org/3/", None)}
 # A dictionary of graphviz graph attributes for inheritance diagrams.
 inheritance_graph_attrs = {"rankdir": "TB"}
 
-# Common links that should be available on every page
-rst_epilog = """
-.. _Diamond Light Source: http://www.diamond.ac.uk
-.. _black: https://github.com/psf/black
-.. _ruff: https://beta.ruff.rs/docs/
-.. _mypy: http://mypy-lang.org/
-.. _pre-commit: https://pre-commit.com/
-"""
-
 # Ignore localhost links for periodic check that links in docs are valid
 linkcheck_ignore = [r"http://localhost:\d+/"]
 
@@ -126,7 +128,7 @@ copybutton_prompt_is_regexp = True
 # a list of builtin themes.
 #
 html_theme = "pydata_sphinx_theme"
-github_repo = project
+github_repo = "edge-containers-cli"
 github_user = "epics-containers"
 switcher_json = f"https://{github_user}.github.io/{github_repo}/switcher.json"
 switcher_exists = requests.get(switcher_json).ok
@@ -142,10 +144,10 @@ if not switcher_exists:
 # Theme options for pydata_sphinx_theme
 # We don't check switcher because there are 3 possible states for a repo:
 # 1. New project, docs are not published so there is no switcher
-# 2. Existing project with latest skeleton, switcher exists and works
-# 3. Existing project with old skeleton that makes broken switcher,
+# 2. Existing project with latest copier template, switcher exists and works
+# 3. Existing project with old copier template that makes broken switcher,
 #    switcher exists but is broken
-# Point 3 makes checking switcher difficult, because the updated skeleton
+# Point 3 makes checking switcher difficult, because the updated copier template
 # will fix the switcher at the end of the docs workflow, but never gets a chance
 # to complete as the docs build warns and fails.
 html_theme_options = {
@@ -167,19 +169,13 @@ html_theme_options = {
     },
     "check_switcher": False,
     "navbar_end": ["theme-switcher", "icon-links", "version-switcher"],
-    "external_links": [
-        {
-            "name": "Release Notes",
-            "url": f"https://github.com/{github_user}/{github_repo}/releases",
-        }
-    ],
     "navigation_with_keys": False,
 }
 
 # A dictionary of values to pass into the template engine’s context for all pages
 html_context = {
     "github_user": github_user,
-    "github_repo": project,
+    "github_repo": github_repo,
     "github_version": version,
     "doc_path": "docs",
 }
@@ -192,4 +188,4 @@ html_show_copyright = False
 
 # Logo
 html_logo = "images/dls-logo.svg"
-html_favicon = "images/dls-favicon.ico"
+html_favicon = html_logo

edge_containers_cli-5.3.0a3/docs/explanations/decisions/0001-record-architecture-decisions.md

@@ -0,0 +1,18 @@
+# 1. Record architecture decisions
+
+## Status
+
+Accepted
+
+## Context
+
+We need to record the architectural decisions made on this project.
+
+## Decision
+
+We will use Architecture Decision Records, as [described by Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions).
+
+## Consequences
+
+See Michael Nygard's article, linked above. To create new ADRs we will copy and
+paste from existing ones.

edge_containers_cli-5.3.0a3/docs/explanations/decisions/0002-switched-to-python-copier-template.md

@@ -0,0 +1,28 @@
+# 2. Adopt python-copier-template for project structure
+
+## Status
+
+Accepted
+
+## Context
+
+We should use the following [python-copier-template](https://github.com/DiamondLightSource/python-copier-template).
+The template will ensure consistency in developer
+environments and package management.
+
+## Decision
+
+We have switched to using the template.
+
+## Consequences
+
+This module will use a fixed set of tools as developed in `python-copier-template`
+and can pull from this template to update the packaging to the latest techniques.
+
+As such, the developer environment may have changed, the following could be
+different:
+
+- linting
+- formatting
+- pip venv setup
+- CI/CD

edge_containers_cli-5.3.0a3/docs/explanations/decisions/COPYME

@@ -0,0 +1,19 @@
+# 3. Short descriptive title
+
+Date: Today's date
+
+## Status
+
+Accepted
+
+## Context
+
+Background to allow us to make the decision, to show how we arrived at our conclusions.
+
+## Decision
+
+What decision we made.
+
+## Consequences
+
+What we will do as a result of this decision.

edge_containers_cli-5.3.0a3/docs/explanations/decisions.md

@@ -0,0 +1,12 @@
+# Architectural Decision Records
+
+Architectural decisions are made throughout a project's lifetime. As a way of keeping track of these decisions, we record these decisions in Architecture Decision Records (ADRs) listed below.
+
+```{toctree}
+:glob: true
+:maxdepth: 1
+
+decisions/*
+```
+
+For more information on ADRs see this [blog by Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions).

edge_containers_cli-5.3.0a3/docs/explanations.md

@@ -0,0 +1,10 @@
+# Explanations
+
+Explanations of how it works and why it works that way.
+
+```{toctree}
+:maxdepth: 1
+:glob:
+
+explanations/*
+```

edge_containers_cli-5.3.0a3/docs/genindex.md

@@ -0,0 +1,3 @@
+# Index
+
+<!-- Placeholder that sphinx will replace with a generated index -->

edge_containers_cli-5.3.0a3/docs/how-to/contribute.md

@@ -0,0 +1,2 @@
+```{include} ../../.github/CONTRIBUTING.md
+```

edge_containers_cli-5.3.0a3/docs/how-to/run-container.md

@@ -0,0 +1,14 @@
+# Run in a container
+
+Pre-built containers with edge-containers-cli and its dependencies already
+installed are available on [Github Container Registry](https://ghcr.io/epics-containers/edge-containers-cli).
+
+## Starting the container
+
+To pull the container from github container registry and run:
+
+```
+$ docker run ghcr.io/epics-containers/edge-containers-cli:latest --version
+```
+
+To get a released version, use a numbered release instead of `latest`.

edge_containers_cli-5.3.0a3/docs/how-to.md

@@ -0,0 +1,10 @@
+# How-to Guides
+
+Practical step-by-step guides for the more experienced user.
+
+```{toctree}
+:maxdepth: 1
+:glob:
+
+how-to/*
+```

edge_containers_cli-5.3.0a3/docs/images/dls-logo.svg

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg width="120" height="120" version="1.1" xmlns="http://www.w3.org/2000/svg">
+ <g transform="matrix(.37271 0 0 .37271 -3.343e-7 .0014878)" stroke-width="2.6831">
+  <path d="m0 160.98c0-88.908 72.073-160.98 160.98-160.98 88.911 0 160.99 72.073 160.99 160.98 0 88.907-72.075 160.98-160.99 160.98-88.908 0-160.98-72.073-160.98-160.98" fill="#fff"/>
+  <path d="m222.71 254.64c-8.56 1.2229-11.317 7.8871-6.1307 14.802l23.701 31.598c23.669-13.431 43.611-32.657 57.855-55.791l-75.425 9.3905" fill="#facf07"/>
+  <path d="m99.553 220.97c8.5615-1.2224 11.319-7.8813 6.1319-14.797l-61.997-82.665c-5.1911-6.916-3.7729-8.3307 3.1437-3.144l82.652 61.988c6.9161 5.192 13.575 2.4293 14.797-6.1267l14.613-150.7c1.2187-8.5613 3.2227-8.5613 4.4467 0l14.612 150.72c1.224 8.5573 7.8827 11.315 14.799 6.128l82.684-62.011c6.916-5.1867 8.3293-3.772 3.1427 3.144l-62.001 82.669c-5.1867 6.9161-2.4293 13.575 6.132 14.799l83.085 10.343c10.348-21.254 16.16-45.119 16.16-70.35 0-88.897-72.069-160.97-160.97-160.97-88.902 0-160.97 72.069-160.97 160.97 0 25.244 5.8208 49.123 16.173 70.381l83.369-10.38" fill="#facf07"/>
+  <path d="m144.28 299.39c-1.2227-8.5563-7.8813-11.314-14.798-6.1307l-24.743 18.561c13.459 5.0198 27.784 8.2651 42.676 9.5104l-3.136-21.941" fill="#facf07"/>
+  <path d="m177.95 299.37-3.1347 21.941c14.869-1.2682 29.163-4.5323 42.604-9.5682l-24.667-18.504c-6.9213-5.188-13.58-2.4255-14.803 6.1308" fill="#facf07"/>
+  <path d="m99.553 254.65-75.744-9.4307c14.288 23.215 34.315 42.503 58.086 55.946l23.79-31.718c5.1875-6.9145 2.4296-13.573-6.1319-14.797" fill="#facf07"/>
+ </g>
+</svg>

edge_containers_cli-5.3.0a3/docs/index.md

@@ -0,0 +1,56 @@
+---
+html_theme.sidebar_secondary.remove: true
+---
+
+```{include} ../README.md
+:end-before: <!-- README only content
+```
+
+
+How the documentation is structured
+-----------------------------------
+
+Documentation is split into [four categories](https://diataxis.fr), also accessible from links in the top bar.
+
+<!-- https://sphinx-design.readthedocs.io/en/latest/grids.html -->
+
+::::{grid} 2
+:gutter: 4
+
+:::{grid-item-card} {material-regular}`directions_walk;2em`
+```{toctree}
+:maxdepth: 2
+tutorials
+```
++++
+Tutorials for installation and typical usage. New users start here.
+:::
+
+:::{grid-item-card} {material-regular}`directions;2em`
+```{toctree}
+:maxdepth: 2
+how-to
+```
++++
+Practical step-by-step guides for the more experienced user.
+:::
+
+:::{grid-item-card} {material-regular}`info;2em`
+```{toctree}
+:maxdepth: 2
+explanations
+```
++++
+Explanations of how it works and why it works that way.
+:::
+
+:::{grid-item-card} {material-regular}`menu_book;2em`
+```{toctree}
+:maxdepth: 2
+reference
+```
++++
+Technical reference material including APIs and release notes.
+:::
+
+::::