From 5665cfb4b8871503d5bcc79e73a4f475184c1124 Mon Sep 17 00:00:00 2001
From: Dima Tisnek <dima.tisnek@canonical.com>
Date: Tue, 3 Sep 2024 15:34:51 +0900
Subject: [PATCH] docs: text for 'main page'

---
 docs/index.rst | 100 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 100 insertions(+)

diff --git a/docs/index.rst b/docs/index.rst
index af4de65ca..5c745aee1 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -2,6 +2,21 @@
 ops library API reference
 =========================
 
+The `ops` library is a Python framework for building and testing Juju charms.
+It is the recommended way to write charms for both Kubernetes and machines.
+
+What It Does
+------------
+
+The `ops` library provides powerful constructs for charm developers:
+
+- **Interact with Juju**: `ops` offers the API to respond to Juju events
+  and manage application units, relations, storage, secrets and resources.
+- **Manage Workloads**: For Kubernetes charms, `ops.pebble`
+  provides an interface to control services inside the workload containers.
+- **Write Unit Tests**: `ops.testing` is the unit testing framework for
+  your charm.
+
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
@@ -9,6 +24,34 @@ ops library API reference
 ops module
 ==========
 
+Quick Start Example
+-------------------
+
+Here’s a simple charm example using the `ops` library:
+
+.. code-block:: python
+
+    #!/usr/bin/env python3
+    import ops
+
+
+    class FastAPIDemoCharm(ops.CharmBase):
+        """Charm the service."""
+
+        def __init__(self, framework):
+            super().__init__(framework)
+            framework.observe(self.on.demo_server_pebble_ready, self._on_demo_server_pebble_ready)
+
+        def _on_demo_server_pebble_ready(self, event):
+            event.workload.container.add_layer(...)
+            event.workload.container.replan()
+            self.unit.status = ops.ActiveStatus()
+
+
+    if __name__ == "__main__":  # pragma: nocover
+        ops.main(FastAPIDemoCharm)
+
+
 .. automodule:: ops
    :exclude-members: main
 
@@ -28,12 +71,69 @@ legacy main module
 ops.pebble module
 =================
 
+An example of configuring workload container using pebble.
+
+.. code-block:: python
+
+        def _on_demo_server_pebble_ready(self, event):
+            event.workload.container.add_layer(self._pebble_layer())
+            event.workload.container.replan()
+            self.unit.status = ops.ActiveStatus()
+
+        def _pebble_layer(self) -> ops.pebble.Layer:
+            return ops.pebble.Layer({
+                "services": {
+                    "demo_service": {
+                        "override": "replace",
+                        "startup": "enabled",
+                        "command": ["/some/command", "--some-arg"],
+                        "environment": {
+                            "SOME_ENV_VAR": "some value",
+                        },
+                        # Let the container die if things go wrong
+                        "on-success": "shutdown",
+                        "on-failure": "shutdown",
+                        "on-check-failure": {
+                            "online": "shutdown"
+                        }
+                    }
+                },
+                "checks": {
+                    # A custom check called "online"
+                    "online": {
+                        "override": "replace",
+                        "exec": {
+                            "command": ["/another/command", "--another-arg"],
+                        },
+                        "period": "3s"
+                    }
+                },
+            })
+
 .. automodule:: ops.pebble
 
 
 ops.testing module
 ==================
 
+An example testing a charm using the Harness framework.
+
+.. code-block:: python
+
+    @pytest.fixture
+    def harness():
+        harness = ops.testing.Harness(FastAPIDemoCharm)
+        harness.begin()
+        yield harness
+        harness.cleanup()
+
+
+    def test_pebble_ready(harness):
+        assert harness.model.unit.status == ops.MaintenanceStatus("")
+
+        harness.container_pebble_ready("demo_server")
+        assert harness.model.unit.status == ops.ActiveStatus()
+
 .. automodule:: ops.testing