Lock docs dependencies; build docs with recent Sphinx version

.gitignore

@@ -8,6 +8,7 @@ __pycache__
 *~
 .venv
 venv
+/docsenv
 .vscode
 .coverage
 /.tox

.readthedocs.yaml

@@ -1,6 +1,13 @@
-version: 2                      # required
-formats: []                     # i.e. no extra formats (for now)
+version: 2
+
 python:
-  version: "3.8"
   install:
     - requirements: docs/requirements.txt
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+sphinx:
+   configuration: docs/conf.py

docs/conf.py

@@ -14,7 +14,7 @@
 # -- Project information -----------------------------------------------------
 
 project = 'The Operator Framework'
-copyright = '2019-2020, Canonical Ltd.'
+copyright = '2019-2023, Canonical Ltd.'
 author = 'Canonical Ltd'
 
 
@@ -88,7 +88,7 @@
 #     'signature' – Show typehints as its signature (default)
 #     'description' – Show typehints as content of function or method
 #     'none' – Do not show typehints
-autodoc_typehints = 'description'
+autodoc_typehints = 'signature'
 
 # This value selects what content will be inserted into the main body of an
 # autoclass directive. The possible values are:

docs/requirements.in

@@ -0,0 +1,3 @@
+-r ../requirements.txt
+sphinx==6.2.1  # Latest sphinx_rtd_theme doesn't yet support sphinx 7.x
+sphinx_rtd_theme==1.2.1

docs/requirements.txt

@@ -1,5 +1,25 @@
--r ../requirements.txt
-
-sphinx
-sphinx_rtd_theme
-
+alabaster==0.7.13
+Babel==2.12.1
+certifi==2023.5.7
+charset-normalizer==3.1.0
+docutils==0.18.1
+idna==3.4
+imagesize==1.4.1
+Jinja2==3.1.2
+MarkupSafe==2.1.2
+packaging==23.1
+Pygments==2.15.1
+PyYAML==6.0
+requests==2.31.0
+snowballstemmer==2.2.0
+Sphinx==6.2.1
+sphinx-rtd-theme==1.2.1
+sphinxcontrib-applehelp==1.0.4
+sphinxcontrib-devhelp==1.0.2
+sphinxcontrib-htmlhelp==2.0.1
+sphinxcontrib-jquery==4.1
+sphinxcontrib-jsmath==1.0.1
+sphinxcontrib-qthelp==1.0.3
+sphinxcontrib-serializinghtml==1.1.5
+urllib3==2.0.2
+websocket-client==1.5.2

docs/update_requirements.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+
+# Update and freeze docs/requirements.txt from docs/requirements.in
+
+set -ex
+
+python3 -m venv docsenv
+source docsenv/bin/activate
+pip install -r docs/requirements.in
+pip freeze >docs/requirements.txt
+deactivate
+rm -rf docsenv