Merge pull request #1244 from tmihoc/add-discourse-docs

#1244

As part of a broader move where juju.is docs go federated and RTD, this PR adds all the python-libjuju material we previously had under juju.is/docs/juju (in how-to guide tabs) to the python-libjuju RTD (under a new section called "How-to guides").

This RTD project could use a lot of further improvements (e.g., for all of the other projects -- juju, terraform-provider-juju, charmcraft, ops -- I made sure to update the homepage according to the standard template and to have the full Diataxis tree and integrate the new content nicely with the old, removing duplication, etc.). However, given that we are slowly phasing python-libjuju out, I believe leaving things as is is probably fine.

There is one fix that it is worth making, namely, the links to Juju docs. I followed the instructions in https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide/#internal-references for "targets in other doc sets", but the links don't seem to be working. It could be because the Juju RTD project needs some fixing (we're working on it). I should know soon enough what needs to be done and then I'll come back and fix all the links in a follow-up PR.

#### QA Steps

From the root of the repo:

```
# Build the docs:
tox -e docs 

#Preview the docs:
open docs/_build/index.html
```

.gitignore

@@ -16,3 +16,4 @@ pytestdebug.log
 deb_dist
 *.tar.gz
 .idea/
+build/

docs/conf.py

@@ -48,6 +48,7 @@
     "sphinx.ext.viewcode",
     "sphinxcontrib.asyncio",
     "automembersummary",
+    # 'sphinx_tabs.tabs',
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/howto/index.rst

@@ -0,0 +1,27 @@
+How-to guides
+#############
+
+.. toctree::
+   :glob:
+   :maxdepth: 2
+
+   Manage python-libjuju <manage-python-libjuju>
+   Manage clouds <manage-clouds>
+   Manage credentials <manage-credentials>
+   Manage controllers <manage-controllers>
+   Manage users <manage-users>
+   Manage SSH keys <manage-ssh-keys>
+   Manage models <manage-models>
+   Manage charms <manage-charms>
+   Manage applications <manage-applications>
+   Manage resources (charms) <manage-charm-resources>
+   Manage actions <manage-actions>
+   Manage relations <manage-relations>
+   Manage offers <manage-offers>
+   Manage units <manage-units>
+   Manage secrets <manage-secrets>
+   Manage secret backends <manage-secret-backends>
+   Manage machines <manage-machines>
+   Manage storage <manage-storage>
+   Manage storage pools <manage-storage-pools>
+   Manage spaces <manage-spaces>

docs/howto/manage-actions.rst

@@ -0,0 +1,40 @@
+.. _manage-actions:
+
+How to manage actions
+=====================
+
+
+> See also: :ref:`juju:action`
+
+
+
+List all actions
+----------------
+
+
+To list the actions defined for a deployed application, use the `get_actions()` method on the `Application` object to get all the actions defined for this application.
+
+.. code:: python
+
+   await my_app.get_actions()
+
+
+> See more: `Application (object) <https://pythonlibjuju.readthedocs.io/en/latest/narrative/application.html>`_, `get_actions (method) <https://pythonlibjuju.readthedocs.io/en/latest/api/juju.application.html#juju.application.Application.get_actions>`_
+
+
+Run an action
+
+To run an action on a unit, use the `run_action()` method on a Unit object of a deployed application.
+
+Note that "running" an action on a unit, enqueues an action to be performed. The result will be an Action object to interact with. You will need to call `action.wait()` on that object to wait for the action to complete and retrieve the results.
+
+.. code:: python
+
+   # Assume we deployed a git application
+   my_app = await model.deploy('git', application_name='git', channel='stable')
+   my_unit = my_app.units[0]
+
+   action = await my_unit.run_action('add-repo', repo='myrepo')
+   await action.wait() # will return the result for the action
+
+> See more: `Unit (object) <https://pythonlibjuju.readthedocs.io/en/latest/narrative/unit.html>`_, `Action (object) <https://pythonlibjuju.readthedocs.io/en/latest/api/juju.action.html#juju.action.Action>`_, `Unit.run_action (method) <https://pythonlibjuju.readthedocs.io/en/latest/api/juju.unit.html#juju.unit.Unit.run_action>`_, `Action.wait() (method) <https://pythonlibjuju.readthedocs.io/en/latest/api/juju.action.html#juju.action.Action.wait>`_

docs/howto/manage-applications.rst

@@ -0,0 +1,241 @@
+.. _manage-applications:
+
+How to manage applications
+==========================
+
+> See also: :ref:`juju:application`
+
+Deploy an application
+---------------------
+
+To deploy an application, find and deploy a charm / bundle that delivers it.
+
+> See more: :ref:`deploy-a-charm`
+
+View details about an application
+---------------------------------
+
+To view details about an application on python-libjuju, you may use various `get_*` methods that are defined for applications.
+
+For example, to get the config for an application, call `get_config()` method on an `Application` object:
+
+.. code:: python
+
+   config = await my_app.get_config()
+
+
+> See more: `Application.get_config (method) <https://pythonlibjuju.readthedocs.io/en/latest/api/juju.application.html#juju.application.Application.get_config>`_, `Application (methods) <https://pythonlibjuju.readthedocs.io/en/latest/api/juju.application.html#juju.application.Application>`_
+
+
+Trust an application with a credential
+--------------------------------------
+
+Some applications may require access to the backing cloud in order to fulfil their purpose (e.g., storage-related tasks). In such cases, the remote credential associated with the current model would need to be shared with the application. When the Juju administrator allows this to occur the application is said to be *trusted*.
+
+To trust an application during deployment in python-libjuju, you may call the `Model.deploy()` with the `trust` parameter:
+
+.. code:: python
+
+   await my_model.deploy(..., trust=True, ...)
+
+To trust an application after deployment, you may use the `Application.set_trusted()` method:
+
+.. code:: python
+
+   await my_app.set_trusted(True)
+
+
+> See more: `Application.set_trusted (method) <https://pythonlibjuju.readthedocs.io/en/latest/api/juju.application.html#juju.application.Application.set_trusted>`_, `Application.get_trusted (method) <https://pythonlibjuju.readthedocs.io/en/latest/api/juju.application.html#juju.application.Application.get_trusted>`_
+
+
+Run an application action
+-------------------------
+
+> See more: :ref:`manage-actions`
+
+Configure an application
+------------------------
+
+**Get values.** To view the existing configuration for an application on python-libjuju, you may use the `Application.get_config()` method:
+
+.. code:: python
+
+   config = await my_app.get_config()
+
+
+**Set values.** To set configuration values for an application on python-libjuju:
+
+* To configure an application at deployment, simply provide a `config` map during the `Model.deploy()` call:
+
+.. code:: python
+
+   await my_model.deploy(..., config={'redirect-map':'https://demo'}, ...)
+
+
+* To configure an application post deployment, you may use the `Application.set_config()` method, similar to passing config in the deploy call above:
+
+.. code:: python
+
+   await my_app.set_config(config={'redirect-map':'https://demo'})
+
+
+> See more: `Application.set_config (method) <https://pythonlibjuju.readthedocs.io/en/latest/api/juju.application.html#juju.application.Application.set_config>`_,  `Application.get_config (method) <https://pythonlibjuju.readthedocs.io/en/latest/api/juju.application.html#juju.application.Application.get_config)>`_
+
+
+.. _scale-an-application:
+Scale an application
+--------------------
+
+> See also: :ref:`juju:scaling`
+
+Scale an application vertically
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To scale an application vertically, set constraints for the resources that the application's units will be deployed on.
+
+> See more: :ref:`manage-constraints-for-an-application`
+
+Scale an application horizontally
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To scale an application horizontally, control the number of units.
+
+> See more: :ref:`control-the-number-of-units`
+
+
+Make an application highly available
+------------------------------------
+> See also: :ref:`juju:high-availability`
+
+1. Find out if the charm delivering the application supports high availability natively or not. If the latter, find out what you need to do. This could mean integrating with a load balancing reverse proxy, configuring storage etc.
+
+> See more: `Charmhub <https://charmhub.io/>`_
+
+2. Scale up horizontally as usual.
+
+> See more: {ref}`How to scale an application horizontally <5476md>`
+
+Every time a unit is added to an application, Juju will spread out that application's units, distributing them evenly as supported by the provider (e.g., across multiple availability zones) to best ensure high availability. So long as a cloud's availability zones don't all fail at once, and the charm and the charm's application are well written (changing leaders, coordinating across units, etc.), you can rest assured that cloud downtime will not affect your application.
+
+> See more: `Charmhub | wordpress <https://charmhub.io/wordpress>`_, `Charmhub | mediawiki <https://charmhub.io/mediawiki>`_, `Charmhub | haproxy <https://charmhub.io/haproxy>`_
+
+Integrate an application with another application
+-------------------------------------------------
+
+> See more: :ref:`manage-relations`
+
+
+Manage an application’s public availability over the network
+------------------------------------------------------------
+
+To expose some or all endpoints of an application over a network, you may use the `Application.expose()` method, as follows:
+
+.. code:: python
+
+   await my_app.expose(exposed_endpoints=None) # everything's reachable from 0.0.0.0/0.
+
+
+To expose to specific CIDRs or spaces, you may use an `ExposedEndpoint` object to describe that, as follows:
+
+.. code:: python
+
+   # For spaces
+   await my_app.expose(exposed_endpoints={"": ExposedEndpoint(to_spaces=["alpha"]) })
+
+   # For cidrs
+   await my_app.expose(exposed_endpoints={"": ExposedEndpoint(to_cidrs=["10.0.0.0/24"])})
+
+   # You may use both at the same time too
+   await my_app.expose(exposed_endpoints={
+               "ubuntu": ExposedEndpoint(to_spaces=["alpha"], to_cidrs=["10.0.0.0/24"])
+           })
+
+
+
+To unexpose an application, use the `Application.unexpose()` method:
+
+.. code:: python
+
+   await my_app.unexpose() # unexposes the entire application
+
+   await my_app.unexpose(exposed_endpoints=["ubuntu"]) # unexposes the endpoint named "ubuntu"
+
+
+> See more: `ExposedEndpoint (methods) <https://pythonlibjuju.readthedocs.io/en/latest/api/juju.application.html#juju.application.ExposedEndpoint>`_, `Application.expose() <https://pythonlibjuju.readthedocs.io/en/latest/api/juju.application.html#juju.application.Application.expose>`_,  `Application.unexpose() <https://pythonlibjuju.readthedocs.io/en/latest/api/juju.application.html#juju.application.Application.unexpose>`_
+
+
+.. _manage-constraints-for-an-application:
+Manage constraints for an application
+-------------------------------------
+
+> See also: :ref:`juju:constraint`
+
+**Set values.** To set constraints for application in python-libjuju:
+
+* To set at deployment, simply provide a `constraints` map during the `Model.deploy()` call:
+
+.. code:: python
+
+   await my_model.deploy(..., constraints={'arch': 'amd64', 'mem': 256}, ...)
+
+
+* To set constraints post deployment, you may use the `Application.set_contraints()` method, similar to passing constraints in the deploy call above:
+
+.. code:: python
+
+   await my_app.set_constraints(constraints={'arch': 'amd64', 'mem': 256})
+
+
+**Get values.** To see what constraints are set on an application, use the `Application.get_constraints()` method:
+
+.. code:: python
+
+   await my_app.get_constraints()
+
+
+> See more: `Application.set_contraints() <https://pythonlibjuju.readthedocs.io/en/latest/api/juju.application.html#juju.application.Application.set_constraints>`_, `Application.get_constraints (method) <https://pythonlibjuju.readthedocs.io/en/latest/api/juju.application.html#juju.application.Application.get_constraints>`_
+
+
+Change space bindings for an application
+----------------------------------------
+
+To set bindings for an application on python-libjuju, simply pass the `bind` parameter at the `Model.deploy()` call:
+
+.. code:: python
+
+   await my_model.deploy(..., bind="db=db db-client=db public admin-api=public", ...)
+
+Python-libjuju currently doesn't support resetting space bindings post deployment, please use the `juju-cli` for that.
+
+> See more: [`Model.deploy()` (method) <5476md>`
+
+Upgrade an application
+----------------------
+
+To upgrade an application, update its charm.
+
+> See more: :ref:`update-a-charm`
+
+.. _remove-an-application:
+
+Remove an application
+---------------------
+
+> See also: :ref:`juju:removing-things`
+
+To remove an application from a model in python-libjuju, you have two choices:
+
+(1) If you have a reference to a connected model object (connected to the model you're working on), then you may use the `Model.remove_application()` method:
+
+.. code:: python
+
+   await my_model.remove_application(my_app.name)
+
+
+(2) If you have a reference to the application you want to remove, then you may use the `Application.destroy()` directly on the application object you want to remove:
+
+.. code:: python
+
+   await my_app.destroy()
+
+> See more: `Model.remove_application (method) <https://pythonlibjuju.readthedocs.io/en/latest/api/juju.model.html#juju.model.Model.remove_application>`_, `Application.destroy (method) <https://pythonlibjuju.readthedocs.io/en/latest/api/juju.application.html#juju.application.Application.destroy>`_

docs/howto/manage-charm-resources.rst

@@ -0,0 +1,52 @@
+.. _manage-charm-resources:
+
+How to manage charm resources
+=============================
+
+> See also: :ref:`juju:resource-charm`
+
+When you deploy / update an application from a charm, that automatically deploys / updates any charm resources, using the defaults specified by the charm author. However, you can also specify resources manually (e.g., to try a resource released only to `edge` or to specify a non-Charmhub resource). This document shows you how.
+
+
+Find out the resources available for a charm
+--------------------------------------------
+
+To find out what resources are available for a charm on Charmhub, on a connected Model object, select the `charmhub` object associated with the model, and use the `list_resources()` method, passing the name of the charm as an argument. For example:
+
+.. code:: python
+
+   await model.charmhub.list_resources('postgresql-k8s')
+
+> See more: `charmhub (property) <https://pythonlibjuju.readthedocs.io/en/latest/api/juju.model.html#juju.model.Model.charmhub>`_, `Model (module) <https://pythonlibjuju.readthedocs.io/en/latest/narrative/model.html>`_
+
+Specify the resources to be deployed with a charm
+-------------------------------------------------
+
+To specify a resource during deployment, on a connected Model object, use the `deploy` method, passing the resources as a parameter. For example:
+
+.. code:: python
+
+   resources = {"file-res": "test.file"}
+   app = await model.deploy(charm_path, resources=resources)
+
+To update a resource after deployment by uploading file from local disk, on an Application object, use the `attach_resource()` method, passing resource name, file name and the file object as parameters.
+
+.. code:: python
+
+   with open(str(charm_path / 'test.file')) as f:
+       app.attach_resource('file-res', 'test.file', f)
+
+
+
+> See more: `deploy() <https://pythonlibjuju.readthedocs.io/en/latest/api/juju.model.html#juju.model.Model.deploy>`_, `attach_resource() <https://pythonlibjuju.readthedocs.io/en/latest/api/juju.application.html#juju.application.Application.attach_resource>`_, `Model (module) <https://pythonlibjuju.readthedocs.io/en/latest/narrative/model.html>`_
+
+View the resources deployed with a charm
+----------------------------------------
+
+To view the resources that have been deployed with a charm, on an Application object, use the `get_resources()` method. For example:
+
+.. code:: python
+
+   await my_app.get_resources()
+
+> See more: `get_resources() <https://pythonlibjuju.readthedocs.io/en/latest/api/juju.application.html#juju.application.Application.get_resources>`_, `Model (module) <https://pythonlibjuju.readthedocs.io/en/latest/narrative/model.html>`_