From: Tim Van Steenburgh <tvansteenburgh@gmail.com>
Date: Tue, 13 Dec 2016 15:32:06 +0000 (-0500)
Subject: Docs
X-Git-Tag: 0.1.0~14
X-Git-Url: https://osm.etsi.org/gitweb/?a=commitdiff_plain;h=843e6a04a7f92cc7efdcc75ae0bb4be3fb0ca027;p=osm%2FN2VC.git

Docs
---

diff --git a/docs/narrative/application.rst b/docs/narrative/application.rst
new file mode 100644
index 0000000..c255a37
--- /dev/null
+++ b/docs/narrative/application.rst
@@ -0,0 +1,72 @@
+Applications
+============
+
+
+Deploying
+---------
+To deploy a new application, connect a model and then call its
+:meth:`~juju.model.Model.deploy` method. An
+:class:`~juju.application.Application` instance is returned.
+
+.. code:: python
+
+  from juju.model import Model
+
+  model = Model()
+  await model.connect_current()
+
+  mysql_app = await model.deploy(
+      # If a revision number is not included in the charm url,
+      # the latest revision from the Charm Store will be used.
+      'cs:mysql-55',
+      application_name='mysql',
+      series='trusty',
+      channel='stable',
+      config={
+          'tuning-level': 'safest',
+      },
+      constraints={
+          'mem': 256 * MB,
+      },
+  )
+
+
+Adding Units
+------------
+To add units to a deployed application, use the
+:meth:`juju.application.Application.add_units` method. A list of the newly
+added units (:class:`~juju.unit.Unit` objects) is returned.
+
+.. code:: python
+
+    ubuntu_app = await model.deploy(
+        'ubuntu',
+        application_name='ubuntu',
+        series='trusty',
+        channel='stable',
+    )
+
+    unit_a, unit_b = await ubuntu_app.add_units(count=2)
+
+
+Updating Config and Constraints
+-------------------------------
+Example showing how to update configuration and constraints on a deployed
+application. The `mysql_app` object is an instance of
+:class:`juju.application.Application`.
+
+.. code:: python
+
+  MB = 1024 * 1024
+
+  # Update and check app config
+  await mysql_app.set_config({'tuning-level': 'fast'})
+  config = await mysql_app.get_config()
+
+  assert(config['tuning-level']['value'] == 'fast')
+
+  # update and check app constraints
+  await mysql_app.set_constraints({'mem': 512 * MB})
+  constraints = await mysql_app.get_constraints()
+
+  assert(constraints['mem'] == 512 * MB)
diff --git a/docs/narrative/connect-controller.rst b/docs/narrative/connect-controller.rst
deleted file mode 100644
index ac62c1a..0000000
--- a/docs/narrative/connect-controller.rst
+++ /dev/null
@@ -1,98 +0,0 @@
-Connecting to a Controller
-==========================
-A Juju controller provides websocket endpoints for itself and each of its
-models. In order to do anything useful, the juju lib must connect to one of
-these endpoints.
-
-Connecting to the controller endpoint is useful if you want to programmatically
-create a new model. If the model you want to use already exists, you can
-connect directly to it (see :doc:`connect-model`).
-
-
-To the Current Controller
--------------------------
-Connect to the currently active Juju controller (the one returned by
-`juju switch`). This only works if you have the Juju CLI client installed.
-
-.. code:: python
-
-  from juju.controller import Controller
-
-  controller = Controller()
-  await controller.connect_current()
-
-
-To a Named Controller
----------------------
-Connect to a controller by name.
-
-.. code:: python
-
-  from juju.controller import Controller
-
-  controller = Controller()
-  await controller.connect_controller('mycontroller')
-
-
-To an API Endpoint with Username/Password Authentication
---------------------------------------------------------
-The most flexible, but also most verbose, way to connect is using the API
-endpoint url and credentials directly. This method does NOT require the Juju
-CLI client to be installed.
-
-.. code:: python
-
-  from juju.controller import Controller
-
-  controller = Controller()
-
-  controller_endpoint = '10.0.4.171:17070'
-  username = 'admin'
-  password = 'f53f08cfc32a2e257fe5393271d89d62'
-
-  # Left out for brevity, but if you have a cert string you should pass it in.
-  # You can copy the cert from the output of The `juju show-controller`
-  # command.
-  cacert = None
-
-  await controller.connect(
-      controller_endpoint,
-      username,
-      password,
-      cacert,
-  )
-
-
-To an API Endpoint with Macaroon Authentication
------------------------------------------------
-To connect to a shared controller, you'll need
-to use macaroon authentication. The simplest example is shown below, and uses
-already-discharged macaroons from the local filesystem. This will work if you
-have the Juju CLI installed.
-
-.. note::
-
-  The library does not yet contain support for fetching and discharging
-  macaroons. Until it does, if you want to use macaroon auth, you'll need
-  to supply already-discharged macaroons yourself.
-
-.. code:: python
-
-  from juju.client.connection import get_macaroons()
-  from juju.controller import Controller
-
-  controller = Controller()
-
-  controller_endpoint = '10.0.4.171:17070'
-  username = None
-  password = None
-  cacert = None
-  macaroons = get_macaroons()
-
-  await controller.connect(
-      controller_endpoint,
-      username,
-      password,
-      cacert,
-      macaroons,
-  )
diff --git a/docs/narrative/connect-model.rst b/docs/narrative/connect-model.rst
deleted file mode 100644
index c9eea2c..0000000
--- a/docs/narrative/connect-model.rst
+++ /dev/null
@@ -1,103 +0,0 @@
-Connecting to a Model
-=====================
-A Juju controller provides websocket endpoints for itself and each of its
-models. In order to do anything useful, the juju lib must connect to one of
-these endpoints. There are several ways to do this.
-
-
-To the Current Model
---------------------
-Connect to the currently active Juju model (the one returned by
-`juju switch`). This only works if you have the Juju CLI client installed.
-
-.. code:: python
-
-  from juju.model import Model
-
-  model = Model()
-  await model.connect_current()
-
-
-To a Named Model
-----------------
-Connect to a model by name, using the same format as that returned from the
-`juju switch` command. The accepted format is '[controller:][user/]model'.
-This only works if you have the Juju CLI client installed.
-
-.. code:: python
-
-  # $ juju switch
-  # juju-2.0.1:admin/libjuju
-
-  from juju.model import Model
-
-  model = Model()
-  await model.connect_model('juju-2.0.1:admin/libjuju')
-
-
-To an API Endpoint with Username/Password Authentication
---------------------------------------------------------
-The most flexible, but also most verbose, way to connect is using the API
-endpoint url and credentials directly. This method does NOT require the Juju
-CLI client to be installed.
-
-.. code:: python
-
-  from juju.model import Model
-
-  model = Model()
-
-  controller_endpoint = '10.0.4.171:17070'
-  model_uuid = 'e8399ac7-078c-4817-8e5e-32316d55b083'
-  username = 'admin'
-  password = 'f53f08cfc32a2e257fe5393271d89d62'
-
-  # Left out for brevity, but if you have a cert string you should pass it in.
-  # You can copy the cert from the output of The `juju show-controller`
-  # command.
-  cacert = None
-
-  await model.connect(
-      controller_endpoint,
-      model_uuid,
-      username,
-      password,
-      cacert,
-  )
-
-
-To an API Endpoint with Macaroon Authentication
------------------------------------------------
-To connect to a shared model, or a model an a shared controller, you'll need
-to use macaroon authentication. The simplest example is shown below, and uses
-already-discharged macaroons from the local filesystem. This will work if you
-have the Juju CLI installed.
-
-.. note::
-
-  The library does not yet contain support for fetching and discharging
-  macaroons. Until it does, if you want to use macaroon auth, you'll need
-  to supply already-discharged macaroons yourself.
-
-.. code:: python
-
-  from juju.client.connection import get_macaroons()
-  from juju.model import Model
-
-  model = Model()
-
-  controller_endpoint = '10.0.4.171:17070'
-  model_uuid = 'e8399ac7-078c-4817-8e5e-32316d55b083'
-  username = None
-  password = None
-  cacert = None
-  macaroons = get_macaroons()
-
-  await model.connect(
-      controller_endpoint,
-      model_uuid,
-      username,
-      password,
-      cacert,
-      macaroons,
-  )
diff --git a/docs/narrative/controller.rst b/docs/narrative/controller.rst
new file mode 100644
index 0000000..c6f4e0a
--- /dev/null
+++ b/docs/narrative/controller.rst
@@ -0,0 +1,98 @@
+Controllers
+===========
+A Juju controller provides websocket endpoints for itself and each of its
+models. In order to do anything useful, the juju lib must connect to one of
+these endpoints.
+
+Connecting to the controller endpoint is useful if you want to programmatically
+create a new model. If the model you want to use already exists, you can
+connect directly to it (see :doc:`model`).
+
+
+Connecting to the Current Controller
+------------------------------------
+Connect to the currently active Juju controller (the one returned by
+`juju switch`). This only works if you have the Juju CLI client installed.
+
+.. code:: python
+
+  from juju.controller import Controller
+
+  controller = Controller()
+  await controller.connect_current()
+
+
+Connecting to a Named Controller
+--------------------------------
+Connect to a controller by name.
+
+.. code:: python
+
+  from juju.controller import Controller
+
+  controller = Controller()
+  await controller.connect_controller('mycontroller')
+
+
+Connecting with Username/Password Authentication
+------------------------------------------------
+The most flexible, but also most verbose, way to connect is using the API
+endpoint url and credentials directly. This method does NOT require the Juju
+CLI client to be installed.
+
+.. code:: python
+
+  from juju.controller import Controller
+
+  controller = Controller()
+
+  controller_endpoint = '10.0.4.171:17070'
+  username = 'admin'
+  password = 'f53f08cfc32a2e257fe5393271d89d62'
+
+  # Left out for brevity, but if you have a cert string you should pass it in.
+  # You can copy the cert from the output of The `juju show-controller`
+  # command.
+  cacert = None
+
+  await controller.connect(
+      controller_endpoint,
+      username,
+      password,
+      cacert,
+  )
+
+
+Connecting with Macaroon Authentication
+---------------------------------------
+To connect to a shared controller, you'll need
+to use macaroon authentication. The simplest example is shown below, and uses
+already-discharged macaroons from the local filesystem. This will work if you
+have the Juju CLI installed.
+
+.. note::
+
+  The library does not yet contain support for fetching and discharging
+  macaroons. Until it does, if you want to use macaroon auth, you'll need
+  to supply already-discharged macaroons yourself.
+
+.. code:: python
+
+  from juju.client.connection import get_macaroons()
+  from juju.controller import Controller
+
+  controller = Controller()
+
+  controller_endpoint = '10.0.4.171:17070'
+  username = None
+  password = None
+  cacert = None
+  macaroons = get_macaroons()
+
+  await controller.connect(
+      controller_endpoint,
+      username,
+      password,
+      cacert,
+      macaroons,
+  )
diff --git a/docs/narrative/create-model.rst b/docs/narrative/create-model.rst
deleted file mode 100644
index b0cdbe7..0000000
--- a/docs/narrative/create-model.rst
+++ /dev/null
@@ -1,23 +0,0 @@
-Creating and Destroying a Model
-===============================
-Example of creating a new model and then destroying it. See
-:meth:`juju.controller.Controller.add_model` and
-:meth:`juju.controller.Controller.destroy_model` for more info.
-
-.. code:: python
-
-  from juju.controller import Controller
-
-  controller = Controller()
-  await controller.connect_current()
-
-  # Create our new model
-  model = await controller.add_model(
-      'mymodel',  # name of your new model
-  )
-
-  # Do stuff with our model...
-
-  # Destroy the model
-  await model.disconnect()
-  await controller.destroy_model(model.info.uuid)
diff --git a/docs/narrative/index.rst b/docs/narrative/index.rst
index 47c2695..ac5b816 100644
--- a/docs/narrative/index.rst
+++ b/docs/narrative/index.rst
@@ -5,4 +5,6 @@ Narrative Docs
    :glob:
    :maxdepth: 2
 
-   *
+   controller
+   model
+   application
diff --git a/docs/narrative/model.rst b/docs/narrative/model.rst
new file mode 100644
index 0000000..c27179d
--- /dev/null
+++ b/docs/narrative/model.rst
@@ -0,0 +1,129 @@
+Models
+======
+A Juju controller provides websocket endpoints for each of its
+models. In order to do anything useful with a model, the juju lib must
+connect to one of these endpoints. There are several ways to do this.
+
+
+Connecting to the Current Model
+-------------------------------
+Connect to the currently active Juju model (the one returned by
+`juju switch`). This only works if you have the Juju CLI client installed.
+
+.. code:: python
+
+  from juju.model import Model
+
+  model = Model()
+  await model.connect_current()
+
+
+Connecting to a Named Model
+---------------------------
+Connect to a model by name, using the same format as that returned from the
+`juju switch` command. The accepted format is '[controller:][user/]model'.
+This only works if you have the Juju CLI client installed.
+
+.. code:: python
+
+  # $ juju switch
+  # juju-2.0.1:admin/libjuju
+
+  from juju.model import Model
+
+  model = Model()
+  await model.connect_model('juju-2.0.1:admin/libjuju')
+
+
+Connecting with Username/Password Authentication
+------------------------------------------------
+The most flexible, but also most verbose, way to connect is using the API
+endpoint url and credentials directly. This method does NOT require the Juju
+CLI client to be installed.
+
+.. code:: python
+
+  from juju.model import Model
+
+  model = Model()
+
+  controller_endpoint = '10.0.4.171:17070'
+  model_uuid = 'e8399ac7-078c-4817-8e5e-32316d55b083'
+  username = 'admin'
+  password = 'f53f08cfc32a2e257fe5393271d89d62'
+
+  # Left out for brevity, but if you have a cert string you should pass it in.
+  # You can copy the cert from the output of The `juju show-controller`
+  # command.
+  cacert = None
+
+  await model.connect(
+      controller_endpoint,
+      model_uuid,
+      username,
+      password,
+      cacert,
+  )
+
+
+Connecting with Macaroon Authentication
+---------------------------------------
+To connect to a shared model, or a model an a shared controller, you'll need
+to use macaroon authentication. The simplest example is shown below, and uses
+already-discharged macaroons from the local filesystem. This will work if you
+have the Juju CLI installed.
+
+.. note::
+
+  The library does not yet contain support for fetching and discharging
+  macaroons. Until it does, if you want to use macaroon auth, you'll need
+  to supply already-discharged macaroons yourself.
+
+.. code:: python
+
+  from juju.client.connection import get_macaroons()
+  from juju.model import Model
+
+  model = Model()
+
+  controller_endpoint = '10.0.4.171:17070'
+  model_uuid = 'e8399ac7-078c-4817-8e5e-32316d55b083'
+  username = None
+  password = None
+  cacert = None
+  macaroons = get_macaroons()
+
+  await model.connect(
+      controller_endpoint,
+      model_uuid,
+      username,
+      password,
+      cacert,
+      macaroons,
+  )
+
+
+Creating and Destroying a Model
+-------------------------------
+Example of creating a new model and then destroying it. See
+:meth:`juju.controller.Controller.add_model` and
+:meth:`juju.controller.Controller.destroy_model` for more info.
+
+.. code:: python
+
+  from juju.controller import Controller
+
+  controller = Controller()
+  await controller.connect_current()
+
+  # Create our new model
+  model = await controller.add_model(
+      'mymodel',  # name of your new model
+  )
+
+  # Do stuff with our model...
+
+  # Destroy the model
+  await model.disconnect()
+  await controller.destroy_model(model.info.uuid)
+  model = None