move ops.Container summary to ops/__init__.py; write ops.pebble summary

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

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.
 """

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