feat: optionally install Scenario with ops[testing] and expose the names in ops.testing

docs/custom_conf.py

@@ -18,33 +18,17 @@
 
 from docutils import nodes
 
+import inspect
+import sphinx.ext.autodoc
 from sphinx import addnodes
 from sphinx.util.docutils import SphinxDirective
 
-import furo
-import furo.navigation
 
 sys.path.insert(0, str(pathlib.Path(__file__).parent.parent))
 
-# Furo patch to get local TOC to show in sidebar (as sphinx-rtd-theme did)
-# See https://github.com/pradyunsg/furo/blob/490527b2aef00b1198770c3389a1979911ee1fcb/src/furo/__init__.py#L115-L128
-
-_old_compute_navigation_tree = furo._compute_navigation_tree
-
-
-def _compute_navigation_tree(context):
-    tree_html = _old_compute_navigation_tree(context)
-    if not tree_html and context.get('toc'):
-        tree_html = furo.navigation.get_navigation_tree(context['toc'])
-    return tree_html
-
-
-furo._compute_navigation_tree = _compute_navigation_tree
-
 # Pull in fix from https://github.com/sphinx-doc/sphinx/pull/11222/files to fix
 # "invalid signature for autoattribute ('ops.pebble::ServiceDict.backoff-delay')"
-import re  # noqa: E402
-import sphinx.ext.autodoc  # noqa: E402
+import re
 
 sphinx.ext.autodoc.py_ext_sig_re = re.compile(
     r"""^ ([\w.]+::)?            # explicit module name
@@ -216,7 +200,9 @@ def _compute_navigation_tree(context):
 # pyspelling, sphinx, sphinx-autobuild, sphinx-copybutton, sphinx-design,
 # sphinx-notfound-page, sphinx-reredirects, sphinx-tabs, sphinxcontrib-jquery,
 # sphinxext-opengraph
-custom_required_modules = []
+custom_required_modules = [
+    'ops-scenario>=7.0.5,<8',
+]
 
 # Add files or directories that should be excluded from processing.
 custom_excludes = [
@@ -315,6 +301,8 @@ def _compute_navigation_tree(context):
     # Please keep this list sorted alphabetically.
     ('py:class', '_ChangeDict'),
     ('py:class', '_CheckInfoDict'),
+    ('py:class', '_EntityStatus'),
+    ('py:class', '_Event'),
     ('py:class', '_FileInfoDict'),
     ('py:class', '_NoticeDict'),
     ('py:class', '_ProgressDict'),
@@ -326,6 +314,8 @@ def _compute_navigation_tree(context):
     ('py:class', '_TextOrBinaryIO'),
     ('py:class', '_WarningDict'),
     ('py:class', '_Writeable'),
+    ('py:class', 'AnyJson'),
+    ('py:class', 'CharmType'),
     ('py:obj', 'ops._private.harness.CharmType'),
     ('py:class', 'ops._private.harness.CharmType'),
     ('py:class', 'ops.charm._ContainerBaseDict'),
@@ -345,9 +335,34 @@ def _compute_navigation_tree(context):
     ('py:class', 'ops.testing._ConfigOption'),
     ('py:class', 'ops.testing.CharmType'),
     ('py:obj', 'ops.testing.CharmType'),
+    ('py:class', 'scenario.state._EntityStatus'),
+    ('py:class', 'scenario.state._Event'),
+    ('py:class', 'scenario.state._max_posargs.<locals>._MaxPositionalArgs'),
 ]
 
 
+# Monkeypatch Sphinx to look for __init__ rather than __new__ for the subclasses
+# of _MaxPositionalArgs.
+_real_get_signature = sphinx.ext.autodoc.ClassDocumenter._get_signature
+
+
+def _custom_get_signature(self):
+    if any(p.__name__ == '_MaxPositionalArgs' for p in self.object.__mro__):
+        signature = inspect.signature(self.object)
+        parameters = []
+        for position, param in enumerate(signature.parameters.values()):
+            if position >= self.object._max_positional_args:
+                parameters.append(param.replace(kind=inspect.Parameter.KEYWORD_ONLY))
+            else:
+                parameters.append(param)
+        signature = signature.replace(parameters=parameters)
+        return None, None, signature
+    return _real_get_signature(self)
+
+
+sphinx.ext.autodoc.ClassDocumenter._get_signature = _custom_get_signature
+
+
 # This is very strongly based on
 # https://github.com/sphinx-doc/sphinx/blob/03b9134ee00e98df4f8b5f6d22f345cdafe31870/sphinx/domains/changeset.py#L46
 # Unfortunately, the built-in class is not easily subclassable without also

docs/harness.rst

@@ -0,0 +1,31 @@
+:orphan:
+
+.. _harness:
+
+Harness Unit Test Framework
+===========================
+
+.. deprecated:: 2.17
+    The Harness framework is deprecated and will be moved out of the base
+    install in a future ops release.
+
+The Harness framework includes:
+
+- :class:`ops.testing.Harness`, a class to set up the simulated environment,
+  that provides:
+
+  - :meth:`~ops.testing.Harness.add_relation` method, to declare a relation
+    (integration) with another app.
+  - :meth:`~ops.testing.Harness.begin` and :meth:`~ops.testing.Harness.cleanup`
+    methods to start and end the testing lifecycle.
+  - :meth:`~ops.testing.Harness.evaluate_status` method, which aggregates the
+    status of the charm after test interactions.
+  - :attr:`~ops.testing.Harness.model` attribute, which exposes e.g. the
+    :attr:`~ops.Model.unit` attribute for detailed assertions on the unit's state.
+
+.. autoclass:: ops.testing.ActionFailed
+   :noindex:
+.. autoclass:: ops.testing.ActionOutput
+.. autoclass:: ops.testing.ExecArgs
+.. autoclass:: ops.testing.ExecResult
+.. autoclass:: ops.testing.Harness

docs/index.rst

@@ -1,79 +1,86 @@
-
-ops library API reference
-=========================
+API reference
+=============
 
 The `ops` library is a Python framework for writing and testing Juju charms.
 
   See more: `Charm SDK documentation <https://juju.is/docs/sdk>`_
 
-The library provides:
+The library (`available on PyPI`_) provides:
 
 - :ref:`ops_main_entry_point`, used to initialise and run your charm;
 - :ref:`ops_module`, the API to respond to Juju events and manage the application;
 - :ref:`ops_pebble_module`, the Pebble client, a low-level API for Kubernetes containers;
-- :ref:`ops_testing_module`, the framework for unit testing charms in a simulated environment;
+- :ref:`ops_testing_module` frameworks for unit testing charms in a simulated environment;
 
 You can structure your charm however you like, but with the `ops` library, you
 get a framework that promotes consistency and readability by following best
 practices. It also helps you organise your code better by separating different
-aspects of the charm, such as managing the application’s state, handling
+aspects of the charm, such as managing the application's state, handling
 integrations with other services, and making the charm easier to test.
 
+.. _available on PyPI: https://pypi.org/project/ops/
 
 .. toctree::
+   :hidden:
    :maxdepth: 2
-   :caption: Contents:
 
+   self
+   state-transition-testing
+   harness
 
 .. _ops_module:
 
-ops module
-==========
+ops
+---
 
 .. automodule:: ops
    :exclude-members: main
 
-
 .. _ops_main_entry_point:
 
 ops.main entry point
-====================
+--------------------
 
 The main entry point to initialise and run your charm.
 
 .. autofunction:: ops.main
 
-
 legacy main module
 ------------------
 
 .. automodule:: ops.main
    :noindex:
 
-
 .. _ops_pebble_module:
 
-ops.pebble module
-=================
+ops.pebble
+----------
 
 .. automodule:: ops.pebble
 
-
 .. _ops_testing_module:
 
-ops.testing module
-==================
+Testing
+-------
+
+Two frameworks for unit testing charms in a simulated Juju environment are
+available:
+
+* :doc:`State-transition testing </state-transition-testing>`, which tests the charm's state transitions in response
+  to events. This is the recommended approach. Install ops with the ``testing``
+  extra to use this framework; for example: ``pip install ops[testing]``
+* :doc:`Harness </harness>`, which provides an API reminiscent of the Juju CLI. This is a
+  deprecated framework, and has issues, particularly with resetting the charm
+  state between Juju events. It will be moved out of the base ``ops`` install in
+  a future release.
+
 
-.. autoclass:: ops.testing.ActionFailed
-.. autoclass:: ops.testing.ActionOutput
-.. autoclass:: ops.testing.ExecArgs
-.. autoclass:: ops.testing.ExecResult
-.. autoclass:: ops.testing.Harness
+.. note::
+    Unit testing is only one aspect of a comprehensive testing strategy. For more
+    on testing charms, see `Charm SDK | Testing <https://juju.is/docs/sdk/testing>`_.
 
 
 Indices
 =======
 
 * :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`

docs/requirements.txt

@@ -1,5 +1,5 @@
 #
-# This file is autogenerated by pip-compile with Python 3.12
+# This file is autogenerated by pip-compile with Python 3.11
 # by the following command:
 #
 #    pip-compile --extra=docs --output-file=docs/requirements.txt pyproject.toml
@@ -73,6 +73,10 @@ 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
@@ -85,7 +89,9 @@ pyspelling==2.10
 pyyaml==6.0.2
     # via
     #   myst-parser
+    #   ops
     #   ops (pyproject.toml)
+    #   ops-scenario
     #   pyspelling
 requests==2.32.3
     # via
@@ -160,6 +166,8 @@ wcmatch==9.0
 webencodings==0.5.1
     # via html5lib
 websocket-client==1.8.0
-    # via ops (pyproject.toml)
+    # via
+    #   ops
+    #   ops (pyproject.toml)
 websockets==12.0
     # via sphinx-autobuild