docs: add top-level intro and module-level intros

CHANGES.md

@@ -159,7 +159,7 @@
 
 ## Features
 
-* `StopEvent`, `RemoveEvent`, and all `LifeCycleEvent`s are no longer deferrable, and will raise a `RuntimeError` if `defer()` is called on the event object (#1122)
+* `StopEvent`, `RemoveEvent`, and all `LifecycleEvent`s are no longer deferrable, and will raise a `RuntimeError` if `defer()` is called on the event object (#1122)
 * Add `ActionEvent.id`, exposing the JUJU_ACTION_UUID environment variable (#1124)
 * Add support for creating `pebble.Plan` objects by passing in a `pebble.PlanDict`, the
   ability to compare two `Plan` objects with `==`, and the ability to create an empty Plan with `Plan()` (#1134)

docs/index.rst

@@ -2,19 +2,47 @@
 ops library API reference
 =========================
 
+The `ops` library is a Python framework for writing and testing Juju charms.
+
+For more about the Charm SDK, see https://juju.is/docs/sdk.
+
+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` 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
+framework that helps you write consistent readable charms following the latest
+best practices, reuse code via charm libs, and separate typical charm concerns
+--- application state management from integration management or lifecycle
+management from testability.
+
+Whether you are a machine or a Kubernetes charm author, `ops` is the recommended way to go.
+
+
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
+
+.. _ops_module:
+
 ops module
 ==========
 
 .. automodule:: ops
    :exclude-members: main
 
 
+.. _ops_main_entry_point:
+
 ops.main entry point
 ====================
+
+The main entry point to initialise and run your charm.
+
 .. autofunction:: ops.main
 
 
@@ -25,12 +53,16 @@ legacy main module
    :noindex:
 
 
+.. _ops_pebble_module:
+
 ops.pebble module
 =================
 
 .. automodule:: ops.pebble
 
 
+.. _ops_testing_module:
+
 ops.testing module
 ==================
 

ops/__init__.py

@@ -12,31 +12,50 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""The ops library: a Python framework for writing Juju charms.
+"""The API to respond to Juju events and manage the application.
 
-The ops library is a Python framework (`available on PyPI`_) for developing
-and testing Juju charms in a consistent way, using standard Python constructs
-to allow for clean, maintainable, and reusable code.
+This module provides:
 
-A charm is an operator -- business logic encapsulated in a reusable software
-package that automates every aspect of an application's life.
+- :class:`~ops.CharmBase` and :class:`~ops.Object` to register the charm or
+  a charm lib, respectively, with the framework.
+- [OPT1] :class:`~ops.framework.EventBase` class and individual event types, like
+  :class:`~ops.ActionEvent` class.
+- [OPT2] :class:`~ops.framework.EventBase` and its subclasses:
 
-Charms written with ops support Kubernetes using Juju's "sidecar charm"
-pattern, as well as charms that deploy to Linux-based machines and containers.
+  - :class:`~ops.HookEvent` class for Juju events, like the
+    :class:`~ops.StartEvent` class.
+  - :class:`~ops.LifecycleEvent` class for synthetic events, like the
+    :class:`~ops.CollectStatusEvent` class.
 
-Charms should do one thing and do it well. Each charm drives a single
-application and can be integrated with other charms to deliver a complex
-system. A charm handles creating the application in addition to scaling,
-configuration, optimisation, networking, service mesh, observability, and other
-day-2 operations specific to the application.
+- :class:`~ops.Framework` class, accessible as ``self.framework`` in a charm,
+  the main interface for the charm to `ops` library infrastructure, including:
 
-The ops library is part of the Charm SDK (the other part being Charmcraft).
-Full developer documentation for the Charm SDK is available at
-https://juju.is/docs/sdk.
+  - :meth:`~ops.Framework.on` shorthand property used to
+    :meth:`~ops.Framework.observe` and react to Juju events.
+  - :attr:`~ops.Framework.model` attribute to get hold of the Model instance.
 
-To learn more about Juju, visit https://juju.is/docs/olm.
+- :class:`~ops.model.Model` class that represents the Juju Model, including:
 
-.. _available on PyPI: https://pypi.org/project/ops/
+  - :attr:`~ops.Model.app` attribute, representing the application associated
+    with the charm.
+  - :attr:`~ops.Model.unit` attribute, representing the unit of the application
+    the charm is running on.
+  - :attr:`~ops.Model.relations` attribute, which provides access to relations
+    defined in the charm, allowing interaction with other applications.
+  - :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.
 """
 
 # The "from .X import Y" imports below don't explicitly tell Pyright (or MyPy)

ops/model.py

@@ -2304,7 +2304,11 @@ def start(self, *service_names: str):
         self._pebble.start_services(service_names)
 
     def restart(self, *service_names: str):
-        """Restart the given service(s) by name."""
+        """Restart the given service(s) by name.
+
+        Listed running services will be stopped and restarted, and listed stopped
+        services will be started.
+        """
         if not service_names:
             raise TypeError('restart expected at least 1 argument, got 0')
 

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

ops/testing.py

@@ -11,8 +11,25 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+"""Framework for unit testing charms in a simulated environment.
 
-"""Infrastructure to build unit tests for charms using the ops library."""
+The module provides:
+
+- :class:`ops.testing.Harness`, a class to set up the environment for charms, and its:
+
+  - :meth:`~ops.testing.Harness.begin_with_initial_hooks` convenience method for declarative
+    test setup.
+  - individual :meth:`~ops.testing.Harness.begin` and :meth:`~ops.testing.Harness.cleanup`
+    methods to start and end the testing lifecycle.
+  - :meth:`~ops.testing.Harness.evaluate_status` method, which aggregates the
+    status of the charm after test interactions.
+  - :attr:`~ops.testing.Harness.model` attribute, which exposes e.g. the
+    :attr:`~ops.Model.unit` attribute for detailed assertions on the unit's state.
+
+.. note::
+    Unit testing is only one aspect of a comprehensive testing strategy. For more
+    on testing charms, see `Testing Strategies <https://juju.is/docs/sdk/testing>`_.
+"""
 
 import dataclasses
 import datetime