Docs

diff --git a/Makefile b/Makefile
index 07a459a..eaf18a6 100644 (file)
--- a/Makefile
+++ b/Makefile
@@ -17,7 +17,7 @@ test:
        tox
 
 docs: .tox
-       $(PIP) list | grep Sphinx || $(PIP) install -U sphinx
+       $(PIP) install -r docs/requirements.txt
        rm -rf docs/api/* docs/_build/
        $(BIN)/sphinx-apidoc -o docs/api/ juju/
        $(BIN)/sphinx-build -b html docs/  docs/_build/

diff --git a/docs/conf.py b/docs/conf.py
index a856985..973ef9a 100644 (file)
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -37,6 +37,7 @@ extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.todo',
     'sphinx.ext.viewcode',
+    'sphinxcontrib.asyncio',
 ]
 
 # Add any paths that contain templates here, relative to this directory.

diff --git a/docs/narrative/model.rst b/docs/narrative/model.rst
index 036f43f..79df011 100644 (file)
--- a/docs/narrative/model.rst
+++ b/docs/narrative/model.rst
@@ -224,3 +224,26 @@ to the entity and type of change that you wish to handle.
       async def on_change(self, delta, old, new, model):
           # The catch-all handler - will be called whenever a more
           # specific handler method is not defined.
+
+
+Any :class:`juju.model.ModelEntity` object can be observed directly by
+registering callbacks on the object itself.
+
+.. code:: python
+
+  import logging
+
+  async def on_app_change(delta, old, new, model):
+      logging.debug('App changed: %r', new)
+
+  async def on_app_remove(delta, old, new, model):
+      logging.debug('App removed: %r', old)
+
+  ubuntu_app = await model.deploy(
+      'ubuntu',
+      application_name='ubuntu',
+      series='trusty',
+      channel='stable',
+  )
+  ubuntu_app.on_change(on_app_change)
+  ubuntu_app.on_remove(on_app_remove)

diff --git a/docs/requirements.txt b/docs/requirements.txt
new file mode 100644 (file)
index 0000000..3bd387e
--- /dev/null
+++ b/docs/requirements.txt
@@ -0,0 +1,2 @@
+sphinx
+sphinxcontrib-asyncio