docs: use the right ops-scenario for building the docs (#1470)

This PR fixes the version of ops-scenario used when building the docs.

Previously, the published version of ops-scenario was used for
generating the documentation, and the generated requirements file was
used for local builds but not for read-the-docs.

That breaks if there are local incompatible changes (such as renaming a
module), and is generally wrong anyway.

With this PR, the local version is loaded, and read-the-docs uses the
same requirements file as building locally. A few minor type annotations
were adjusted to remove remaining warnings (I don't know why Sphinx
couldn't figure out where `Path` was coming from, but keeping it in the
`pathlib` namespace is generally nicer anyway).

Split out from #1467.

.readthedocs.yaml

@@ -2,10 +2,7 @@ version: 2
 
 python:
   install:
-    - method: pip
-      path: .
-      extra_requirements:
-        - docs
+    - requirements: docs/requirements.txt
 
 build:
   os: ubuntu-22.04

docs/custom_conf.py

@@ -212,9 +212,7 @@
 # pyspelling, sphinx, sphinx-autobuild, sphinx-copybutton, sphinx-design,
 # sphinx-notfound-page, sphinx-reredirects, sphinx-tabs, sphinxcontrib-jquery,
 # sphinxext-opengraph
-custom_required_modules = [
-    'ops-scenario>=7.0.5,<8',
-]
+custom_required_modules = []
 
 # Add files or directories that should be excluded from processing.
 custom_excludes = [
@@ -318,6 +316,7 @@
     ('py:class', '_FileInfoDict'),
     ('py:class', '_NoticeDict'),
     ('py:class', '_ProgressDict'),
+    ('py:class', '_RawPortProtocolLiteral'),
     ('py:class', '_Readable'),
     ('py:class', '_RelationMetaDict'),
     ('py:class', '_ResourceMetaDict'),
@@ -347,6 +346,8 @@
     ('py:class', 'ops.testing._ConfigOption'),
     ('py:class', 'ops.testing.CharmType'),
     ('py:obj', 'ops.testing.CharmType'),
+    ('py:obj', 'scenario.state.CharmType'),
+    ('py:class', 'scenario.state.CharmType'),
     ('py:class', 'scenario.state._EntityStatus'),
     ('py:class', 'scenario.state._Event'),
     ('py:class', 'scenario.state._max_posargs.<locals>._MaxPositionalArgs'),

docs/requirements.txt

@@ -73,10 +73,6 @@ mdurl==0.1.2
     # via markdown-it-py
 myst-parser==4.0.0
     # via ops (pyproject.toml)
-ops==2.16.1
-    # via ops-scenario
-ops-scenario==7.0.5
-    # via ops (pyproject.toml)
 packaging==24.1
     # via sphinx
 pygments==2.18.0
@@ -89,9 +85,7 @@ pyspelling==2.10
 pyyaml==6.0.2
     # via
     #   myst-parser
-    #   ops
     #   ops (pyproject.toml)
-    #   ops-scenario
     #   pyspelling
 requests==2.32.3
     # via
@@ -166,8 +160,7 @@ wcmatch==9.0
 webencodings==0.5.1
     # via html5lib
 websocket-client==1.8.0
-    # via
-    #   ops
-    #   ops (pyproject.toml)
+    # via ops (pyproject.toml)
 websockets==12.0
     # via sphinx-autobuild
+./testing/

pyproject.toml

@@ -36,7 +36,6 @@ docs = [
     "sphinx-tabs",
     "sphinxcontrib-jquery",
     "sphinxext-opengraph",
-    "ops-scenario>=7.0.5,<8",
 ]
 testing = [
     "ops-scenario>=7.0.5,<8",

testing/src/scenario/state.py

@@ -9,12 +9,12 @@
 import dataclasses
 import datetime
 import inspect
+import pathlib
 import random
 import re
 import string
 from enum import Enum
 from itertools import chain
-from pathlib import Path, PurePosixPath
 from typing import (
     TYPE_CHECKING,
     Any,
@@ -747,9 +747,9 @@ def _run(self) -> int:
 class Mount(_max_posargs(0)):
     """Maps local files to a :class:`Container` filesystem."""
 
-    location: str | PurePosixPath
+    location: str | pathlib.PurePosixPath
     """The location inside of the container."""
-    source: str | Path
+    source: str | pathlib.Path
     """The content to provide when the charm does :meth:`ops.Container.pull`."""
 
 
@@ -1017,7 +1017,7 @@ def services(self) -> dict[str, pebble.ServiceInfo]:
             infos[name] = info
         return infos
 
-    def get_filesystem(self, ctx: Context) -> Path:
+    def get_filesystem(self, ctx: Context) -> pathlib.Path:
         """Simulated Pebble filesystem in this context.
 
         Returns:
@@ -1314,7 +1314,7 @@ def __eq__(self, other: object) -> bool:
             return (self.name, self.index) == (other.name, other.index)
         return False
 
-    def get_filesystem(self, ctx: Context) -> Path:
+    def get_filesystem(self, ctx: Context) -> pathlib.Path:
         """Simulated filesystem root in this context."""
         return ctx._get_storage_root(self.name, self.index)
 
@@ -1325,7 +1325,7 @@ class Resource(_max_posargs(0)):
 
     name: str
     """The name of the resource, as found in the charm metadata."""
-    path: str | Path
+    path: str | pathlib.Path
     """A local path that will be provided to the charm as the content of the resource."""
 
 
@@ -1589,7 +1589,7 @@ class _CharmSpec(Generic[CharmType]):
     is_autoloaded: bool = False
 
     @staticmethod
-    def _load_metadata_legacy(charm_root: Path):
+    def _load_metadata_legacy(charm_root: pathlib.Path):
         """Load metadata from charm projects created with Charmcraft < 2.5."""
         # back in the days, we used to have separate metadata.yaml, config.yaml and actions.yaml
         # files for charm metadata.
@@ -1606,7 +1606,7 @@ def _load_metadata_legacy(charm_root: Path):
         return meta, config, actions
 
     @staticmethod
-    def _load_metadata(charm_root: Path):
+    def _load_metadata(charm_root: pathlib.Path):
         """Load metadata from charm projects created with Charmcraft >= 2.5."""
         metadata_path = charm_root / "charmcraft.yaml"
         meta: dict[str, Any] = (
@@ -1624,7 +1624,7 @@ def autoload(charm_type: type[CharmBase]) -> _CharmSpec[CharmType]:
 
         Will attempt to load the metadata off the ``charmcraft.yaml`` file
         """
-        charm_source_path = Path(inspect.getfile(charm_type))
+        charm_source_path = pathlib.Path(inspect.getfile(charm_type))
         charm_root = charm_source_path.parent.parent
 
         # attempt to load metadata from unified charmcraft.yaml

tox.ini

@@ -40,6 +40,7 @@ description = Compile the requirements.txt file for docs
 deps = pip-tools
 commands =
     pip-compile --extra=docs -o docs/requirements.txt pyproject.toml
+    python -c 'open("docs/requirements.txt", "a").write("./testing/\n")'
 
 [testenv:docs]
 description = Build the Sphinx docs