Add an examples section

docs/examples/creating_resources.md

@@ -0,0 +1,47 @@
+# Creating Resources
+
+## Create a Pod
+
+Create a new Pod.
+
+`````{tab-set}
+
+````{tab-item} Sync
+```python
+from kr8s.objects import Pod
+
+pod = Pod({
+        "apiVersion": "v1",
+        "kind": "Pod",
+        "metadata": {
+            "name": "my-pod",
+        },
+        "spec": {
+            "containers": [{"name": "pause", "image": "gcr.io/google_containers/pause",}]
+        },
+    })
+
+pod.create()
+```
+````
+
+````{tab-item} Async
+```python
+from kr8s.asyncio.objects import Pod
+
+pod = await Pod({
+        "apiVersion": "v1",
+        "kind": "Pod",
+        "metadata": {
+            "name": "my-pod",
+        },
+        "spec": {
+            "containers": [{"name": "pause", "image": "gcr.io/google_containers/pause",}]
+        },
+    })
+
+await pod.create()
+```
+````
+
+`````

docs/examples/index.md

@@ -0,0 +1,10 @@
+# Examples
+
+This section contains code examples to demonstrate what you can do with `kr8s`.
+
+```{toctree}
+creating_resources
+listing_resources
+modifying_resources
+labelling_operator
+```

docs/examples/labelling_operator.md

@@ -0,0 +1,146 @@
+# Labelling Operator
+
+Build an operator that periodically reconciles all Deployments and adds a label to any with a certain annotation.
+
+```{warning}
+While you can build operators with `kr8s` we would recommend folks look at using [kopf](https://kopf.readthedocs.io/en/stable/) for building anything more complex than the below example.
+```
+
+## Controller
+
+First we need to create a Python script called `controller.py` containing the controller code that uses `kr8s`.
+
+`````{tab-set}
+
+````{tab-item} Sync
+```python
+# controller.py
+import time
+import kr8s
+
+def run():
+    while True:
+        for deploy in kr8s.get("deployments", namespace=kr8s.ALL):
+            if 'pykube-test-operator' in deploy.annotations:
+                deploy.label(foo="bar")
+        time.sleep(15)
+
+if __name__ == "__main__":
+    run()
+```
+````
+
+````{tab-item} Async
+```python
+# controller.py
+import asyncio
+import kr8s
+
+async def run():
+    while True:
+        for deploy in await kr8s.asyncio.get("deployments", namespace=kr8s.ALL):
+            if 'pykube-test-operator' in deploy.annotations:
+                await deploy.label(foo="bar")
+        await asyncio.sleep(15)
+
+if __name__ == "__main__":
+    asyncio.run(run())
+```
+````
+
+`````
+
+## Packaging
+
+Now we can package our controller code in a container image.
+
+```dockerfile
+# Dockerfile
+FROM python:3.11
+
+WORKDIR /usr/local/src
+
+RUN pip install kr8s
+
+COPY controller.py /usr/local/src/
+
+CMD ["python3", "/usr/local/src/controller.py"]
+```
+
+```console
+$ docker build -t foo/labelling-operator:latest .
+$ docker push foo/labelling-operator:latest
+```
+
+## Deploying
+
+Then to deploy our operator we need to create a ServiceAccount with a ClusterRole for our controller to use to communicate with the Kubernetes API.
+
+```yaml
+# rbac.yaml
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: labelling-operator
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: labelling-operator
+rules:
+- apiGroups:
+  - apps
+  resources:
+  - deployments
+  verbs:
+  - get
+  - watch
+  - list
+  - update
+  - patch
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: labelling-operator
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: labelling-operator
+subjects:
+- kind: ServiceAccount
+  name: labelling-operator
+  namespace: default
+```
+
+```console
+$ kubectl apply -f rbac.yaml
+```
+
+Then create a deployment to run our controller container.
+
+```yaml
+# deployment.yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: labelling-operator
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: labelling-operator
+  template:
+    metadata:
+      labels:
+        app: labelling-operator
+    spec:
+      serviceAccountName: labelling-operator
+      containers:
+      - name: operator
+        image: foo/labelling-operator:latest
+```
+
+```console
+$ kubectl apply -f deployment.yaml
+```

docs/examples/listing_resources.md

@@ -0,0 +1,111 @@
+# Listing resources
+
+## List Nodes
+
+Print out all of the node names in the cluster.
+
+`````{tab-set}
+
+````{tab-item} Sync
+```python
+import kr8s
+
+for node in kr8s.get("nodes"):
+    print(node.name)
+```
+````
+
+````{tab-item} Async
+```python
+import kr8s.asyncio
+
+for node in await kr8s.asyncio.get("nodes"):
+    print(node.name)
+```
+````
+
+`````
+
+## List Pods in all Namespaces
+
+List all Pods in all namespaces and print their IP, namespace and name.
+
+`````{tab-set}
+
+````{tab-item} Sync
+```python
+import kr8s
+
+for pod in kr8s.get("pods", namespace=kr8s.ALL):
+    print(pod.status.podIP, pod.metadata.namespace, pod.metadata.name)
+```
+````
+
+````{tab-item} Async
+```python
+import kr8s
+
+for pod in await kr8s.asyncio.get("pods", namespace=kr8s.ALL):
+    print(pod.status.podIP, pod.metadata.namespace, pod.metadata.name)
+```
+````
+
+`````
+
+## List Ready Pods
+
+Get a list of Pod resources that have the `Ready=True` condition.
+
+`````{tab-set}
+
+````{tab-item} Sync
+```python
+import kr8s
+
+for pod in kr8s.get("pods", namespace="kube-system"):
+    if pod.ready():
+        print(pod.name)
+```
+````
+
+````{tab-item} Async
+```python
+import kr8s
+
+for pod in await kr8s.asyncio.get("pods", namespace="kube-system"):
+    if await pod.ready():
+        print(pod.name)
+```
+````
+
+`````
+
+## List Pods by label selector
+
+Starting from a dictionary containing a label selector get all Pods from all Namespaces matching that label.
+
+`````{tab-set}
+
+````{tab-item} Sync
+```python
+import kr8s
+
+selector = {'component': 'kube-scheduler'}
+
+for pod in kr8s.get("pods", namespace=kr8s.ALL, label_selector=selector):
+    print(pod.namespace, pod.name)
+```
+````
+
+````{tab-item} Async
+```python
+import kr8s
+
+selector = {'component': 'kube-scheduler'}
+
+for pod in await kr8s.asyncio.get("pods", namespace=kr8s.ALL, label_selector=selector):
+    print(pod.namespace, pod.name)
+```
+````
+
+`````

docs/examples/modifying_resources.md

@@ -0,0 +1,27 @@
+# Modifying Resources
+
+## Scale a Deployment
+
+Scale the Deployment `metrics-server` in the Namespace `kube-system` to `1` replica.
+
+`````{tab-set}
+
+````{tab-item} Sync
+```python
+from kr8s.objects import Deployment
+
+deploy = Deployment.get("metrics-server", namespace="kube-system")
+deploy.scale(1)
+```
+````
+
+````{tab-item} Async
+```python
+from kr8s.asyncio.objects import Deployment
+
+deploy = await Deployment.get("metrics-server", namespace="kube-system")
+await deploy.scale(1)
+```
+````
+
+`````

docs/index.md

@@ -62,6 +62,7 @@ See the [Object API docs](https://docs.kr8s.org/en/latest/object.html) for more
 :caption: Getting Started
 :hidden: true
 installation
+examples/index
 ```
 
 ```{toctree}