Merge pull request #911 from cderici/backward-port-sphinx-doc-fix-to-2.9

#911

#### Description

This backports the changes from #899 into the `2.9` branch to have the docs be built successfully for the `2.9` PRs and releases.

#### QA Steps

The `docs` step down in the github actions from the readthedocs should be successfully building.

Author: jujubot

.readthedocs.yaml

@@ -0,0 +1,13 @@
+version: 2
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.10"
+
+sphinx:
+  configuration: docs/conf.py

CONTRIBUTORS

@@ -2,3 +2,10 @@ Benjamin Saller
 Tim Van Steenburgh
 Cory Johns
 Pete VanderGiessen
+Pen Gale
+Juan Tirado Martin
+Caner Derici
+Simon Richardson
+Jack Shaw
+Leon Mintz
+Adam Dyess

Makefile

@@ -24,17 +24,13 @@ test: lint
 	tox -e py3
 	tox -e integration
 
-
 .PHONY: lint
 lint: 
 	tox -e lint
 
 .PHONY: docs
-docs: .tox
-	$(PIP) install -r docs/requirements.txt
-	rm -rf docs/_build/
-	$(BIN)/sphinx-build -b html docs/  docs/_build/
-	cd docs/_build/ && zip -r docs.zip *
+docs:
+	tox -e docs
 
 .PHONY: release
 release:

docs/_extensions/automembersummary.py

@@ -18,9 +18,9 @@
 import textwrap
 
 from docutils import nodes
+from docutils.parsers.rst import Directive
 from docutils.statemachine import ViewList
 from sphinx.errors import SphinxError
-from sphinx.util.compat import Directive
 from sphinx.util.nodes import nested_parse_with_titles
 
 

docs/api/juju.cloud.rst

@@ -77,7 +77,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
@@ -300,4 +300,4 @@
 #texinfo_no_detailmenu = False
 
 def setup(app):
-    app.add_stylesheet('custom.css')
+    app.add_css_file('custom.css')

docs/conf.py

@@ -17,12 +17,10 @@ To deploy a new application, connect a model and then call its
   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',
+      'mysql',
+      application_name='my-mysql',
+      series='jammy',
+      channel='8.0/stable',
       config={
           'tuning-level': 'safest',
       },
@@ -46,9 +44,9 @@ To deploy a local charm, pass the charm directory path to
 
   # Deploy a local charm using a path to the charm directory
   await model.deploy(
-      '/home/tvansteenburgh/src/charms/ubuntu',
+      './charms/ubuntu',
       application_name='ubuntu',
-      series='trusty',
+      series='jammy',
   )
 
 
@@ -63,7 +61,6 @@ added units (:class:`~juju.unit.Unit` objects) is returned.
   ubuntu_app = await model.deploy(
       'ubuntu',
       application_name='ubuntu',
-      series='trusty',
       channel='stable',
   )
 
@@ -107,18 +104,18 @@ The :meth:`juju.application.Application.relate` method returns a
 
   # Deploy mysql-master application
   mysql_master = await model.deploy(
-      'cs:mysql-55',
+      'mysql',
       application_name='mysql-master',
-      series='trusty',
-      channel='stable',
+      series='jammy',
+      channel='8.0/stable',
   )
 
   # Deploy mysql-slave application
   mysql_slave = await model.deploy(
-      'cs:mysql-55',
+      'mysql',
       application_name='mysql-slave',
-      series='trusty',
-      channel='stable',
+      series='jammy',
+      channel='8.0/stable',
   )
 
   # Add the master-slave relation

docs/narrative/application.rst

@@ -6,9 +6,9 @@ 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 py:doc:`model`).
+connect directly to it (see :doc:`model`).
 
-For API docs, see py:class:`juju.controller.Controller`.
+For API docs, see :class:`juju.controller.Controller`.
 
 
 Connecting to the Current Controller

docs/narrative/controller.rst

@@ -4,7 +4,7 @@ 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.
 
-For api docs, see py:class:`juju.model.Model`.
+For api docs, see :class:`juju.model.Model`.
 
 
 Connecting to the Current Model
@@ -92,8 +92,8 @@ require the Juju CLI client to be installed.
 Creating and Destroying a Model
 -------------------------------
 Example of creating a new model and then destroying it. See
-py:method:`juju.controller.Controller.add_model` and
-py:method:`juju.controller.Controller.destroy_model` for more info.
+:method:`juju.controller.Controller.add_model` and
+:method:`juju.controller.Controller.destroy_model` for more info.
 
 .. code:: python
 
@@ -119,8 +119,8 @@ py:method:`juju.controller.Controller.destroy_model` for more info.
 Adding Machines and Containers
 ------------------------------
 To add a machine or container, connect to a model and then call its
-py:method:`~juju.model.Model.add_machine` method. A
-py:class:`~juju.machine.Machine` instance is returned. The machine id
+:method:`~juju.model.Model.add_machine` method. A
+:class:`~juju.machine.Machine` instance is returned. The machine id
 can be used to deploy a charm to a specific machine or container.
 
 .. code:: python
@@ -177,7 +177,7 @@ Reacting to Changes in a Model
 ------------------------------
 To watch for and respond to changes in a model, register an observer with the
 model. The easiest way to do this is by creating a
-py:class:`juju.model.ModelObserver` subclass.
+:class:`juju.model.ModelObserver` subclass.
 
 .. code:: python
 
@@ -268,7 +268,7 @@ to the entity and type of change that you wish to handle.
           # specific handler method is not defined.
 
 
-Any py:class:`juju.model.ModelEntity` object can be observed directly by
+Any :class:`juju.model.ModelEntity` object can be observed directly by
 registering callbacks on the object itself.
 
 .. code:: python

docs/narrative/model.rst

@@ -43,6 +43,9 @@ 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:
 
+.. note::
+
+Pylibjuju requires an already bootstrapped Juju controller to connect to.
 
 .. code:: python
 
@@ -68,9 +71,7 @@ ubuntu charm, then exits:
           # from the stable channel of the Charm Store.
           ubuntu_app = await model.deploy(
             'ubuntu',
-            application_name='ubuntu',
-            series='xenial',
-            channel='stable',
+            application_name='my-ubuntu',
           )
 
           if '--wait' in sys.argv:
@@ -128,5 +129,7 @@ and then, to connect to the current model and fetch status:
 Versioning
 ----------
 
-Pylibjuju releases now track the Juju release cadence. New generated schemas
+The current Pylibjuju release policy tracks the Juju release cadence.
+In particular, whenever Juju makes a latest/stable release, pylibjuju pushes out
+a release with the same version in the following week. Newly generated schemas
 will be updated per Juju releases.