From 2872570950a1957b86adc99b2cdd4f98356531ee Mon Sep 17 00:00:00 2001
From: Dima Tisnek <dima.tisnek@canonical.com>
Date: Tue, 17 Sep 2024 17:32:30 +0900
Subject: [PATCH] move ops.Container summary to ops/__init__.py; write
 ops.pebble summary

---
 docs/index.rst  |  2 +-
 ops/__init__.py | 11 ++++++++++-
 ops/pebble.py   | 15 ++++++++++++++-
 3 files changed, 25 insertions(+), 3 deletions(-)

diff --git a/docs/index.rst b/docs/index.rst
index e87239765..833dab8e2 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -10,7 +10,7 @@ The library provides:
 
 - :ref:`ops_main_entry_point` used to initialise and run your charm.
 - :ref:`ops_module`, the API to respond to Juju events and manage the application.
-- :ref:`ops_pebble_module` to control services and respond to their events for Kubernetes charms.  
+- :ref:`ops_pebble_module` low-level API for Pebble in Kubernetes containers.
 - :ref:`ops_testing_module`, the framework for unit testing charms in a simulated environment.
 
 You can write a charm in any way you want, but with the `ops` library you get a
diff --git a/ops/__init__.py b/ops/__init__.py
index e06e037bf..e2bffb308 100644
--- a/ops/__init__.py
+++ b/ops/__init__.py
@@ -23,7 +23,7 @@
 - [OPT2] :class:`~ops.framework.EventBase` and its subclasses:
 
   - :class:`~ops.HookEvent` class for Juju events, like the
-    :class:`~ops.ActionEvent` class.
+    :class:`~ops.StartEvent` class.
   - :class:`~ops.LifecycleEvent` class for synthetic events, like the
     :class:`~ops.CollectStatusEvent` class.
 
@@ -45,6 +45,15 @@
   - :meth:`~ops.Model.get_secret` method, to access Juju :class:`~ops.Secret`
     objects.
 
+- :class:`~ops.Container` class to control Kubernetes workloads, including:
+
+  - :meth:`~ops.Container.add_layer` and :meth:`~ops.Container.replan` methods
+    to update Pebble configuration.
+  - :meth:`~ops.Container.pull` and :meth:`~ops.Container.push` methods to copy
+    data to and from container, respectively.
+  - :meth:`~ops.Container.exec` method to run arbitrary commands inside the
+    container.
+
 - :class:`~ops.StatusBase` class and individual status types, like
   :class:`~ops.ActiveStatus` class.
 """
diff --git a/ops/pebble.py b/ops/pebble.py
index 785941566..2694ab3ce 100644
--- a/ops/pebble.py
+++ b/ops/pebble.py
@@ -12,7 +12,17 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Client for the Pebble API (HTTP over Unix socket).
+"""Low-level Pebble API.
+
+This module provides:
+
+- :class:`~ops.pebble.Client` class to communicate directly Pebble.
+- :class:`~ops.pebble.Layer` class to define Pebble configuration layers,
+  including:
+
+  - :class:`~ops.pebble.Check` class to represent Pebble checks.
+  - :class:`~ops.pebble.LogTarget` class to represent Pebble log targets.
+  - :class:`~ops.pebble.Service` class to represent Pebble service descriptions.
 
 For a command-line interface for local testing, see test/pebble_cli.py.
 """
@@ -2187,6 +2197,9 @@ def restart_services(
     ) -> ChangeID:
         """Restart services by name and wait (poll) for them to be started.
 
+        Listed running services will be stopped and restarted, and listed stopped
+        services will be started.
+
         Args:
             services: Non-empty list of services to restart.
             timeout: Seconds before restart change is considered timed out (float). If