Merge pull request #899 from cderici/fix-sphinx-doc

#899

#### Description

This is a follow up on #871 , attempting to have stable green RTD builds for generating the pylibjuju docs.

- It adds a tox environment to run the `sphinx-build` locally rather then doing it in the main dev environment.
- It adds a new `.readthedocs.yaml` configuration file (which will be required it looks like by Sep 2023)

#### Notes & Discussion

After the RTD side is stabilized, the actual docs will be revised to keep up-to-date docs for pylibjuju.

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/narrative/application.rst

@@ -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/controller.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/model.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/readme.rst

@@ -40,6 +40,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
 
@@ -65,7 +68,7 @@ ubuntu charm, then exits:
           # from the stable channel of the Charm Store.
           ubuntu_app = await model.deploy(
             'ubuntu',
-            application_name='ubuntu',
+            application_name='my-ubuntu',
           )
 
           if '--wait' in sys.argv:
@@ -124,5 +127,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.

docs/requirements.txt

@@ -1,5 +1,15 @@
-pytz==2021.1
-pymacaroons>=0.13.0,<1.0  # force new version with pynacl instead of libnacl
-sphinx==4.3.2
+pytz
+pymacaroons
+sphinx==5.3.0
 sphinxcontrib-asyncio
 sphinx_rtd_theme
+websockets
+typing-inspect
+pyyaml
+pyasn1
+pyrfc3339
+paramiko
+macaroonbakery
+toposort
+python-dateutil
+kubernetes

tox.ini

@@ -4,7 +4,7 @@
 # and then run "tox" from this directory.
 
 [tox]
-envlist = lint,py3,py38,py39,py310
+envlist = lint,py3,py38,py39,py310,docs
 skipsdist=True
 
 [pytest]
@@ -41,6 +41,15 @@ deps =
     kubernetes
     hvac
 
+[testenv:docs]
+deps =
+    -r docs/requirements.txt
+
+allowlist_externals = rm
+commands =
+    rm -rf docs/_build/
+    sphinx-build -b html docs/ docs/_build/
+
 [testenv:lint]
 commands =
     flake8 {posargs} juju tests examples