Update docs

Author: kaste

CHANGES.txt

@@ -4,73 +4,79 @@ MOCKITO CHANGE LOG
 
 Release 2.0.0 (March 10, 2026)
 ------------------------------
-- Packaging is now fully defined via ``pyproject.toml`` (``hatchling`` backend);
-  the obsolete ``setup.py`` shim has been removed.
-
-- Calling `thenAnswer()` without arguments is now allowed and is treated like
-  `thenReturn()` without arguments: the stubbed method will return `None`.
-
 - Deprecate `verifyNoMoreInteractions` in favor of `ensureNoUnverifiedInteractions`.
 
 - Deprecate `verifyNoUnwantedInteractions` in favor of `verifyExpectedInteractions`.
 
 - Context managers now check usage and any expectations (set via `expect`) on exit. The usage
-  check can be disabled with the environment variable `MOCKITO_CONTEXT_MANAGERS_CHECK_USAGE="0"`.
+  check can be disabled with the environment variable ``MOCKITO_CONTEXT_MANAGERS_CHECK_USAGE="0"``.
 
 - The `between` matcher now supports open ranges, e.g. `between=(0,)` to assert that at least
   0 interactions occurred.
 
-- Added a first-class `InOrder` API via ``mockito.InOrder`` (also available as
-  ``mockito.inorder.InOrder``). The legacy in-order mode only supported one mock at a time;
+- Calling `thenAnswer()` without arguments is now allowed and is treated like
+  `thenReturn()` without arguments: the stubbed method will return `None`.
+
+- Added a first-class `InOrder` API via ``mockito.InOrder``.
+  The legacy in-order mode only supported one mock at a time;
   the new API supports true cross-mock order verification.
 
-  Migration (old limited style -> new style)::
+  Migration::
 
-      # Before (legacy, single-mock order only)
+      # Before
       from mockito import inorder
       inorder.verify(cat).meow()
       inorder.verify(cat).purr()
 
-      # Now (preferred, explicit cross-mock order)
+      # Now
       from mockito import InOrder
-      in_order = InOrder(cat, dog)
+      in_order = InOrder(cat)  # <== pass multiple objects for cross-mock verification!
       in_order.verify(cat).meow()
-      in_order.verify(dog).bark()
+      inorder.verify(cat).purr()
 
 - The legacy in-order verification mode (``inorder.verify(...)``)
   is deprecated in favor of ``InOrder(...)``.
 
 - Added first-class async/await stubbing support: async callables now preserve
-  awaitable behavior for `thenReturn`, `thenRaise`, and `thenAnswer` (including
-  sync and async answer callables), with parity across `when`, `when2`,
-  `patch`, and `expect`.
-  Note that async introspection metadata (e.g. `inspect.iscoroutinefunction`)
-  for stub wrappers is currently implemented only on Python 3.12+.
-
-- Expanded `mock({...})` constructor shorthands:
-  - `"async <name>"` marks methods as async and supports either `...` or a function value.
-  - `{"__enter__": ...}` / `{"__aenter__": ...}` now install default matching
-    `__exit__` / `__aexit__` handlers when not provided.
-  - `{"__iter__": [..]}` and `{"__aiter__": [..]}` now normalize values into
-    proper iterator / async-iterator behavior.
-  - In constructor dict shorthands, zero-argument functions now widen to
-    accept arbitrary call arguments (e.g. `lambda: "ok"` behaves like
-    `lambda *a, **kw: "ok"`).
-
-- Added first-class property/descriptor stubbing support, including class-level property
-  stubbing via `when(F).p.thenReturn(...)` and `thenCallOriginalImplementation()` support for
-  property stubs (including chained answers like
-  `thenReturn(...).thenCallOriginalImplementation()`). Stubbing instance properties now fails
-  fast with clear guidance to use class-level stubbing (`when(F).p...`).
-
-- Added chained stubbing and expectations across call/property hops, e.g.
-  `when(cat).meow().purr().thenReturn(...)`, `when(User).query.filter_by(...).first()`, and
-  `expect(cat, times=1).meow().purr()`, including cleanup that preserves sibling chain branches.
-
-- Allow `...` in fixed argument positions as an ad-hoc `any` matcher.
-  Trailing positional `...` keeps its existing "rest" semantics.
-
-- Extend `captor` to be used as a rest matcher
+  awaitable behavior for `thenReturn`, `thenRaise`, and `thenAnswer`.
+
+  .. note::
+
+     Async introspection metadata (e.g. ``inspect.iscoroutinefunction``)
+     for stub wrappers is currently implemented only on Python 3.12+.
+
+- Expanded ``mock({...})`` constructor shorthands; see :doc:`mock-shorthands`.
+
+- Added first-class property/descriptor stubbing support.
+
+  E.g.::
+
+      class F:
+          @property
+          def p(self):
+              return "orig"
+
+      when(F).p.thenReturn("stub")
+      assert F().p == "stub"
+
+- Added chained stubbing and expectations across call/property hops, e.g.::
+
+      when(cat).meow().purr().thenReturn(...)
+      when(User).query.filter_by(...).first()
+      expect(cat, times=1).meow().purr()
+
+- Allow ``...`` in fixed argument positions as an ad-hoc `any` matcher.
+  Trailing positional ``...`` keeps its existing "rest" semantics.
+
+  E.g.::
+
+      when(api).call("users", active=...).thenReturn("ok")
+      assert api.call("users", active=True) == "ok"
+      api.call("users")  #  will raise InvocationError, kwarg "active" is missing
+
+      when(api).call("users", ...)  # used as a rest matcher as before
+
+- Extend ``captor`` to be used as a rest matcher
 
   E.g., support::
 
@@ -89,7 +95,7 @@ Release 2.0.0 (March 10, 2026)
       mock.do(1, 2, x=3)
       assert call.value == ((1, 2), {"x": 3})
 
-- Added `patch_attr` and `patch_dict` for non-callable monkeypatch-style use cases
+- Added ``patch_attr`` and ``patch_dict`` for non-callable monkeypatch-style use cases
   (e.g. `sys.stdout`, `sys.argv`, and environment/config dictionaries) with
   context-manager support and restoration through `unstub`.
 
@@ -100,7 +106,7 @@ Release 2.0.0 (March 10, 2026)
       with patch_dict(os.environ, {"user": "bob"}): ...
 
 - Added explicit partial-`unstub` targeting by host + attribute name.
-  This complements method-reference partial unstub (e.g. `unstub(cat.meow)`)
+  This complements method-reference partial unstub (e.g. ``unstub(cat.meow)``)
   and supports tuple form and shorthand form, including multiple attributes
   in one call.
 
@@ -111,7 +117,10 @@ Release 2.0.0 (March 10, 2026)
       unstub(cat, "meow")
       unstub((cat, "meow"), (os.path, "exists"))
 
-- Also implemented `unstub("os.path")`
+- Also implemented `unstub("os.path")` - the string variant.
+
+- Packaging is now fully defined via ``pyproject.toml`` (``hatchling`` backend);
+  the obsolete ``setup.py`` shim has been removed.
 
 
 

README.rst

@@ -90,10 +90,10 @@ to your computer, then run ``uv sync`` in the root directory.  Example usage::
 Note: development and docs tooling target Python >=3.12, while the library itself
 supports older Python versions at runtime.
 
-For docs (Python >=3.12), install only the docs dependencies with::
+To install everything (all dependency groups, Python >=3.12), run::
 
-    uv sync --no-dev --group docs
+    uv sync --all-groups
 
-Or to install everything (all dependency groups, Python >=3.12), run::
+Start the sphinx server::
 
-    uv sync --all-groups
+    uv run sphinx-autobuild docs docs/_build/html

docs/_static/custom.css

@@ -0,0 +1,3 @@
+.highlight {
+    background: #f5f5f5;
+}

docs/conf.py

@@ -80,7 +80,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:
@@ -123,21 +123,22 @@
 
 # -- Options for HTML output ----------------------------------------------
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-html_theme = 'alabaster'
+# The theme to use for HTML and HTML Help pages.
+html_theme = 'furo'
 
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
-#html_theme_options = {}
+# Theme options are theme-specific and customize the look and feel of a theme.
+html_theme_options = {
+    'source_repository': 'https://github.com/kaste/mockito-python/',
+    'source_branch': 'master',
+    'source_directory': 'docs/',
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
 #html_theme_path = []
 
 # The name for this set of Sphinx documents.
-# "<project> v<release> documentation" by default.
-#html_title = u'mockito-python v0.6.1'
+# By default Sphinx appends "documentation", but we keep it shorter.
+html_title = f"{project} {release}"
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
 #html_short_title = None
@@ -155,6 +156,7 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
+html_css_files = ['custom.css']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
@@ -170,9 +172,7 @@
 # typographically correct entities.
 #html_use_smartypants = True
 
-# Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
-html_sidebars = { '**': ['localtoc.html', 'relations.html', 'searchbox.html'], }
+# Use theme-provided sidebars.
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.

docs/index.rst

@@ -3,13 +3,12 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-.. module:: mockito
-
-Mockito is a spying framework originally based on the Java library with the same name.
+Mockito
+=======
 
-.. image:: https://github.com/kaste/mockito-python/actions/workflows/test-lint-go.yml/badge.svg
-    :target: https://github.com/kaste/mockito-python/actions/workflows/test-lint-go.yml
+.. module:: mockito
 
+Mockito is a spying framework focusing on ergonomics.
 
 
 Install
@@ -19,7 +18,7 @@ Install
 
     pip install mockito
 
-If you already use `pytest`, consider using the plugin `pytest-mockito <https://github.com/kaste/pytest-mockito>`_.
+If you already use `pytest`, consider using the plugin `pytest-mockito <https://github.com/kaste/pytest-mockito>`_ too.
 
 
 Use

docs/mock-shorthands.rst

@@ -1,7 +1,7 @@
 mock() configuration and shorthands
 ===================================
 
-If you really dig mock driven development, you use dumb ``mock()``s and don't patch
+If you really dig mock driven development, you use dumb `mocks` and don't patch
 real objects and modules all the time.
 
 The standard setup works as expected::
@@ -69,8 +69,8 @@ you also need to define the context/with handlers::
 .. note::
 
     ``__aenter__``, ``__aexit__``, ``__anext__`` are async by definition,
-    use either ``mock({"__aenter__": ...})`` or
-    ``mock({"async __aenter__": ...})``.
+    both ``mock({"__aenter__": ...})`` and
+    ``mock({"async __aenter__": ...})`` are equivalent.
 
 For ``__aiter__``, we have a special shortcode::
 
@@ -107,9 +107,9 @@ We have the same shortcuts available for `__enter__` and `__iter__`::
 
     mock({"__iter__": [4, 5, 6]})  # install handler and wrap in an iterator
 
-Remember or note that when you rather use specced ``mock()``s you're more or less limited by what the spec
-implements.  If you for example use ``aiohttp.ClientSession`` as the blueprint for your mock,
-we already know that ``get`` is async and you don't need to tell mockito so::
+Remember or note that when you rather use specced ``mock()``\ s you're more or less limited by
+what the spec implements.  If you for example use ``aiohttp.ClientSession`` as the blueprint
+for your mock, we already know that ``get`` is async and hence you don't need to tell mockito::
 
     mock({
         "get": lambda: response   # Look up if ClientSession defines "async def get"