chore: upgrade docs dependencies and fix warnings

.github/workflows/ci.yml

@@ -14,7 +14,7 @@ jobs:
         strategy:
             matrix:
                 os: [Ubuntu, Windows, macOS]
-                python-version: ["3.7", "3.8", "3.9", "3.10", "3.11"]
+                python-version: ["3.7", "3.8", "3.9", "3.10", "3.11", "3.12-rc"]
         steps:
             - name: "Check out repository"
               uses: actions/checkout@v3

decoy/__init__.py

@@ -21,7 +21,7 @@ class Decoy:
     You should create a new Decoy instance before each test and call
     [`reset`][decoy.Decoy.reset] after each test. If you use the
     [`decoy` pytest fixture][decoy.pytest_plugin.decoy], this is done
-    automatically. See the [setup guide](../#setup) for more details.
+    automatically. See the [setup guide][] for more details.
 
     !!! example
         ```python
@@ -32,6 +32,8 @@ class Decoy:
 
         decoy.reset()
         ```
+
+    [setup guide]: index.md#setup
     """
 
     def __init__(self) -> None:
@@ -59,7 +61,7 @@ def mock(
     ) -> Any:
         """Create a mock. See the [mock creation guide] for more details.
 
-        [mock creation guide]: ../usage/create/
+        [mock creation guide]: usage/create.md
 
         Arguments:
             cls: A class definition that the mock should imitate.
@@ -94,7 +96,7 @@ def when(
     ) -> "Stub[ReturnT]":
         """Create a [`Stub`][decoy.Stub] configuration using a rehearsal call.
 
-        See [stubbing usage guide](../usage/when/) for more details.
+        See [stubbing usage guide](usage/when.md) for more details.
 
         Arguments:
             _rehearsal_result: The return value of a rehearsal, used for typechecking.
@@ -133,7 +135,7 @@ def verify(
     ) -> None:
         """Verify a mock was called using one or more rehearsals.
 
-        See [verification usage guide](../usage/verify/) for more details.
+        See [verification usage guide](usage/verify.md) for more details.
 
         Arguments:
             _rehearsal_results: The return value of rehearsals, unused except
@@ -174,7 +176,7 @@ def test_create_something(decoy: Decoy):
     def prop(self, _rehearsal_result: ReturnT) -> "Prop[ReturnT]":
         """Create property setter and deleter rehearsals.
 
-        See [property mocking guide](../advanced/properties/) for more details.
+        See [property mocking guide](advanced/properties.md) for more details.
 
         Arguments:
             _rehearsal_result: The property to mock, for typechecking.
@@ -202,7 +204,7 @@ def reset(self) -> None:
 class Stub(Generic[ReturnT]):
     """A rehearsed Stub that can be used to configure mock behaviors.
 
-    See [stubbing usage guide](../usage/when/) for more details.
+    See [stubbing usage guide](usage/when.md) for more details.
     """
 
     def __init__(self, core: StubCore) -> None:
@@ -291,7 +293,7 @@ def then_enter_with(
         The wrapping context manager is compatible with both the synchronous and
         asynchronous context manager interfaces.
 
-        See the [context manager usage guide](../advanced/context-managers/)
+        See the [context manager usage guide](advanced/context-managers.md)
         for more details.
 
         Arguments:
@@ -303,7 +305,7 @@ def then_enter_with(
 class Prop(Generic[ReturnT]):
     """Rehearsal creator for mocking property setters and deleters.
 
-    See [property mocking guide](../advanced/properties/) for more details.
+    See [property mocking guide](advanced/properties.md) for more details.
     """
 
     def __init__(self, core: PropCore) -> None:

decoy/errors.py

@@ -2,7 +2,7 @@
 
 See the [errors guide][] for more details.
 
-[errors guide]: ../usage/errors-and-warnings/#errors
+[errors guide]: usage/errors-and-warnings.md#errors
 """
 from typing import Optional, Sequence
 
@@ -15,7 +15,7 @@ class MockNameRequiredError(ValueError):
 
     See the [MockNameRequiredError guide][] for more details.
 
-    [MockNameRequiredError guide]: ../usage/errors-and-warnings/#mocknamerequirederror
+    [MockNameRequiredError guide]: usage/errors-and-warnings.md#mocknamerequirederror
     """
 
     def __init__(self) -> None:
@@ -32,7 +32,7 @@ class MissingRehearsalError(ValueError):
 
     See the [MissingRehearsalError guide][] for more details.
 
-    [MissingRehearsalError guide]: ../usage/errors-and-warnings/#missingrehearsalerror
+    [MissingRehearsalError guide]: usage/errors-and-warnings.md#missingrehearsalerror
     """
 
     def __init__(self) -> None:
@@ -46,7 +46,7 @@ class MockNotAsyncError(TypeError):
     to a synchronous stub's `then_do` method.
     See the [MockNotAsyncError guide][] for more details.
 
-    [MockNotAsyncError guide]: ../usage/errors-and-warnings/#mocknotasyncerror
+    [MockNotAsyncError guide]: usage/errors-and-warnings.md#mocknotasyncerror
     """
 
 
@@ -55,7 +55,7 @@ class VerifyError(AssertionError):
 
     See [spying with verify][] for more details.
 
-    [spying with verify]: ../usage/verify/
+    [spying with verify]: usage/verify.md
 
     Attributes:
         rehearsals: Rehearsals that were being verified.

decoy/matchers.py

@@ -5,6 +5,9 @@
 
 Matchers help you loosen assertions where strict adherence to an exact value
 is not relevant to what you're trying to test.
+See the [matchers guide][] for more details.
+
+[matchers guide]: usage/matchers.md
 
 !!! example
     ```python

decoy/warnings.py

@@ -2,7 +2,7 @@
 
 See the [warnings guide][] for more details.
 
-[warnings guide]: ../usage/errors-and-warnings/#warnings
+[warnings guide]: usage/errors-and-warnings.md#warnings
 """
 import os
 from typing import Sequence
@@ -25,9 +25,9 @@ class MiscalledStubWarning(DecoyWarning):
     - Configured as a stub with [`when`][decoy.Decoy.when]
     - Called with arguments that do not match any configured behaviors
 
-    See the [MiscalledStubWarning guide] for more details.
+    See the [MiscalledStubWarning guide][] for more details.
 
-    [MiscalledStubWarning guide]: ../usage/errors-and-warnings/#miscalledstubwarning
+    [MiscalledStubWarning guide]: usage/errors-and-warnings.md#miscalledstubwarning
 
     Attributes:
         rehearsals: The mocks's configured rehearsals.
@@ -70,7 +70,7 @@ class RedundantVerifyWarning(DecoyWarning):
 
     See the [RedundantVerifyWarning guide][] for more details.
 
-    [RedundantVerifyWarning guide]: ../usage/errors-and-warnings/#redundantverifywarning
+    [RedundantVerifyWarning guide]: usage/errors-and-warnings.md#redundantverifywarning
     """
 
     def __init__(self, rehearsal: VerifyRehearsal) -> None:
@@ -91,8 +91,7 @@ class IncorrectCallWarning(DecoyWarning):
 
     If a call to a Decoy mock is incorrect according to `inspect.signature`,
     this warning will be raised.
-
     See the [IncorrectCallWarning guide][] for more details.
 
-    [IncorrectCallWarning guide]: ../usage/errors-and-warnings/#incorrectcallwarning
+    [IncorrectCallWarning guide]: usage/errors-and-warnings.md#incorrectcallwarning
     """

docs/usage/errors-and-warnings.md

@@ -61,6 +61,8 @@ my_mock = decoy.mock(name="my_mock")
 
 Decoy uses Python's [warnings system][] to provide feedback about dubious mock usage that isn't _technically_ incorrect. These warnings won't fail your tests, but you probably want to fix them.
 
+[warnings system]: https://docs.python.org/3/library/warnings.html
+
 ### DecoyWarning
 
 A [decoy.warnings.DecoyWarning][] is the base class of all warnings raised by Decoy. This warning will never be raised directly, but can be used in [warning filters][].
@@ -72,6 +74,8 @@ For example, you could set all Decoy warnings to errors or ignore them all entir
 pytestmark = pytest.mark.filterwarnings("ignore::decoy.warnings.DecoyWarning")
 ```
 
+[warning filters]: https://docs.pytest.org/en/latest/how-to/capture-warnings.html
+
 ### MiscalledStubWarning
 
 A [decoy.warnings.MiscalledStubWarning][] is a warning provided mostly for productivity convenience. If you configure a stub but your code under test calls the stub incorrectly, it can sometimes be difficult to immediately figure out what went wrong. This warning exists to alert you if:
@@ -139,6 +143,8 @@ tests/test_example.py::test_subject
 
 These warnings tell us that something probably went wrong with how the dependency was called, allowing us to fix the issue and move on.
 
+[unittest.mock]: https://docs.python.org/3/library/unittest.mock.html
+
 ### RedundantVerifyWarning
 
 A [decoy.warnings.RedundantVerifyWarning][] is a warning provided to prevent you from writing redundant and over-constraining `verify` calls to mocks that have been configured with `when`.