X-Git-Url: https://osm.etsi.org/gitweb/?a=blobdiff_plain;ds=sidebyside;f=docs%2Findex.rst;h=a38e3a48d29f905c03ac46bbd49fe84b2ddc0c6c;hb=51e09af5d8c07e7454cd03b8bf30487a593efa61;hp=67d3fbe579f160ee6abee35918b6a9c97cba0ef5;hpb=17b45c65afac23a123e66834f93049a1c7e45201;p=osm%2FN2VC.git

diff --git a/docs/index.rst b/docs/index.rst
index 67d3fbe..a38e3a4 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -6,58 +6,115 @@
 A Python library for Juju
 =========================
 
-Front Matter
+NOTE: This is pre-release software. The implementation is usable but
+not complete.
+
+Please report bugs at https://github.com/juju/python-libjuju/issues.
+
+
+Requirements
 ------------
 
-NOTE: There is no implementation here yet. It is simply a mocked out
-design of what this library might look like. The design itself is not
-complete. Comments on the design, good or bad, are welcomed. Use cases
-are also appreciated as they will shape the design.
+* Python 3.5+
+* Juju 2.0+
+
+
+Design Notes
+------------
 
-The goal is to end up with a feature-full and officially supported
-python library for Juju.
+* Asynchronous - uses asyncio and async/await features of python 3.5
+* Websocket-level bindings are programmatically generated (indirectly) from the
+  Juju golang code, ensuring full api coverage
+* Provides an OO layer which encapsulates much of the websocket api and
+  provides familiar nouns and verbs (e.g. Model.deploy(), Application.add_unit(),
+  etc.)
 
-The focus right now is on Juju 2+ only.
 
-Design Ideas
+Installation
 ------------
 
-* Present an object-oriented interface to all the features of the Juju
-  CLI
-* Do as much as possible through the API so that the library can be used
-  without actually installing Juju
+    git clone https://github.com/juju/python-libjuju.git
+    cd python-libjuju
+    python setup.py install  # make sure python is 3.5+
 
-Example Use Cases
------------------
 
-Please add more!
+Quickstart
+----------
+Here's a simple example that shows basic usage of the library. The example
+connects to the currently active Juju model, deploys a single unit of the
+ubuntu charm, then exits.
+
+More examples can be found in the `examples/` directory of the source tree,
+and in the documentation.
 
-Simple bootstrap/deploy
-+++++++++++++++++++++++
 
 .. code:: python
 
-  from juju import Juju
+  #!/usr/bin/python3.5
+
+  import asyncio
+  import logging
+
+  from juju.model import Model
+
+
+  async def run():
+      # Create a Model instance. We need to connect our Model to a Juju api
+      # server before we can use it.
+      model = Model()
+
+      # Connect to the currently active Juju model
+      await model.connect_current()
+
+      # Deploy a single unit of the ubuntu charm, using revision 0 from the
+      # stable channel of the Charm Store.
+      ubuntu_app = await model.deploy(
+          'ubuntu-0',
+          application_name='ubuntu',
+          series='xenial',
+          channel='stable',
+      )
+
+      # Disconnect from the api server and cleanup.
+      model.disconnect()
+
+      # Stop the asyncio event loop.
+      model.loop.stop()
+
+
+  def main():
+      # Set logging level to debug so we can see verbose output from the
+      # juju library.
+      logging.basicConfig(level=logging.DEBUG)
+
+      # Quiet logging from the websocket library. If you want to see
+      # everything sent over the wire, set this to DEBUG.
+      ws_logger = logging.getLogger('websockets.protocol')
+      ws_logger.setLevel(logging.INFO)
+
+      # Create the asyncio event loop
+      loop = asyncio.get_event_loop()
+
+      # Queue up our `run()` coroutine for execution
+      loop.create_task(run())
 
-  juju = Juju()
-  lxd = juju.get_cloud('lxd')
-  controller = lxd.bootstrap('lxd-test')
-  model = controller.get_model('default')
+      # Start the event loop
+      loop.run_forever()
 
-  # We might want an async and blocking version of deploy()?
-  model.deploy('mediawiki-single')
 
-  mediawiki = model.get_service('mediawiki')
-  mediawiki.expose()
+  if __name__ == '__main__':
+      main()
 
 
 Table of Contents
 -----------------
 
 .. toctree::
-   :maxdepth: 2
+   :glob:
+   :maxdepth: 3
 
-   api/modules
+   narrative/index
+   API Docs <api/modules>