docs: fix internal references

An update to MkDocstrings means we can use scoped references.

Signed-off-by: JP-Ellis <josh@jpellis.me>

Author: JP-Ellis

examples/plugins/proto/person_pb2_grpc.py

@@ -104,7 +104,8 @@ def GetPerson(
             The response containing the person's details.
 
         Raises:
-            If the method is not implemented.
+            NotImplementedError:
+                If the method is not implemented.
         """
         context.set_code(grpc.StatusCode.UNIMPLEMENTED)
         context.set_details("Method not implemented!")

mkdocs.yml

@@ -61,7 +61,7 @@ plugins:
               ignore_init_summary: true
             docstring_section_style: spacy
             merge_init_into_class: true
-            relative_crossrefs: true
+            # relative_crossrefs: true
             scoped_crossrefs: true
             show_if_no_docstring: true
             # Signature

src/pact/__init__.py

@@ -13,13 +13,13 @@
 
 The primary entry points for contract testing are:
 
--   [`Pact`][pact.Pact]: For consumer-side contract testing, defining expected
+-   [`Pact`][Pact]: For consumer-side contract testing, defining expected
     interactions and generating contract files.
--   [`Verifier`][pact.Verifier]: For provider-side contract verification,
+-   [`Verifier`][Verifier]: For provider-side contract verification,
     validating that a provider implementation satisfies consumer contracts.
 
-These functions are defined in [`pact.pact`][pact.pact] and
-[`pact.verifier`][pact.verifier] and re-exported for convenience.
+These functions are defined in [`pact.pact`][pact] and
+[`pact.verifier`][verifier] and re-exported for convenience.
 
 ### Matching and Generation
 

src/pact/error.py

@@ -77,8 +77,8 @@ class PactVerificationError(PactError):
     All of the errors that occurred during the verification of all of the
     interactions are stored in the `errors` attribute.
 
-    This is different from the [`MismatchesError`][pact.error.MismatchesError]
-    which is raised when there are mismatches detected by the mock server.
+    This is different from the [`MismatchesError`][error.MismatchesError] which
+    is raised when there are mismatches detected by the mock server.
     """
 
     def __init__(self, errors: list[InteractionVerificationError]) -> None:

src/pact/generate/__init__.py

@@ -202,7 +202,7 @@ def integer(
     max: builtins.int | None = None,
 ) -> AbstractGenerator:
     """
-    Alias for [`generate.int`][pact.generate.int].
+    Alias for [`generate.int`][int].
 
     Args:
         min:
@@ -239,7 +239,7 @@ def float(precision: builtins.int | None = None) -> AbstractGenerator:
 
 def decimal(precision: builtins.int | None = None) -> AbstractGenerator:
     """
-    Alias for [`generate.float`][pact.generate.float].
+    Alias for [`generate.float`][float].
 
     Args:
         precision:
@@ -270,7 +270,7 @@ def hex(digits: builtins.int | None = None) -> AbstractGenerator:
 
 def hexadecimal(digits: builtins.int | None = None) -> AbstractGenerator:
     """
-    Alias for [`generate.hex`][pact.generate.hex].
+    Alias for [`generate.hex`][hex].
 
     Args:
         digits:
@@ -301,7 +301,7 @@ def str(size: builtins.int | None = None) -> AbstractGenerator:
 
 def string(size: builtins.int | None = None) -> AbstractGenerator:
     """
-    Alias for [`generate.str`][pact.generate.str].
+    Alias for [`generate.str`][str].
 
     Args:
         size:
@@ -448,7 +448,7 @@ def timestamp(
     disable_conversion: builtins.bool = False,
 ) -> AbstractGenerator:
     """
-    Alias for [`generate.datetime`][pact.generate.datetime].
+    Alias for [`generate.datetime`][datetime].
 
     Returns:
         Generator producing datetimes in the specified format.
@@ -468,7 +468,7 @@ def bool() -> AbstractGenerator:
 
 def boolean() -> AbstractGenerator:
     """
-    Alias for [`generate.bool`][pact.generate.bool].
+    Alias for [`generate.bool`][bool].
 
     Returns:
         Generator producing random boolean values.

src/pact/generate/generator.py

@@ -37,7 +37,7 @@ def to_integration_json(self) -> dict[str, Any]:
         Convert the generator to an integration JSON object.
 
         See
-        [`AbstractGenerator.to_integration_json`][pact.generate.generator.AbstractGenerator.to_integration_json]
+        [`AbstractGenerator.to_integration_json`][AbstractGenerator.to_integration_json]
         for more information.
         """
 
@@ -102,7 +102,7 @@ def to_integration_json(self) -> dict[str, Any]:
         Convert the generator to an integration JSON object.
 
         See
-        [`AbstractGenerator.to_integration_json`][pact.generate.generator.AbstractGenerator.to_integration_json]
+        [`AbstractGenerator.to_integration_json`][AbstractGenerator.to_integration_json]
         for more information.
         """
         return {
@@ -115,7 +115,7 @@ def to_generator_json(self) -> dict[str, Any]:
         Convert the generator to a generator JSON object.
 
         See
-        [`AbstractGenerator.to_generator_json`][pact.generate.generator.AbstractGenerator.to_generator_json]
+        [`AbstractGenerator.to_generator_json`][AbstractGenerator.to_generator_json]
         for more information.
         """
         return {

src/pact/interaction/__init__.py

@@ -2,7 +2,7 @@
 Interaction module.
 
 This module defines the classes that are used to define individual interactions
-within a [`Pact`][pact.pact.Pact] between a consumer and a provider. These
+within a [`Pact`][pact.Pact] between a consumer and a provider. These
 interactions can be of different types, such as HTTP requests, synchronous
 messages, or asynchronous messages.
 

src/pact/interaction/_base.py

@@ -34,9 +34,9 @@ class Interaction(abc.ABC):
     provider. The concrete subclasses define the type of interaction, and
     include:
 
-    -  [`HttpInteraction`][pact.interaction.HttpInteraction]
-    -  [`AsyncMessageInteraction`][pact.interaction.AsyncMessageInteraction]
-    -  [`SyncMessageInteraction`][pact.interaction.SyncMessageInteraction]
+    -  [`HttpInteraction`][HttpInteraction]
+    -  [`AsyncMessageInteraction`][AsyncMessageInteraction]
+    -  [`SyncMessageInteraction`][SyncMessageInteraction]
 
     # Interaction Part
 
@@ -244,8 +244,7 @@ def with_binary_body(
         Adds a binary body to the request or response.
 
         Note that for HTTP interactions, this function will overwrite the body
-        if it has been set using
-        [`with_body`][pact.interaction.Interaction.with_body].
+        if it has been set using [`with_body`][with_body].
 
         Args:
             body:
@@ -295,8 +294,8 @@ def with_metadata(
         The values must be serializable to JSON using [`json.dumps`][json.dumps]
         and may contain matchers and generators. If you wish to use a valid
         JSON-encoded string as a metadata value, prefer the
-        [`set_metadata`][pact.interaction.Interaction.set_metadata] method as
-        this does not perform any additional parsing of the string.
+        [`set_metadata`][set_metadata] method as this does not perform any
+        additional parsing of the string.
 
         Args:
             metadata:
@@ -340,10 +339,9 @@ def set_metadata(
         """
         Add metadata for the interaction.
 
-        This function behaves exactly like
-        [`with_metadata`][pact.interaction.Interaction.with_metadata] but does
-        not perform any parsing of the value strings. The strings must be valid
-        JSON-encoded strings.
+        This function behaves exactly like [`with_metadata`][with_metadata] but
+        does not perform any parsing of the value strings. The strings must be
+        valid JSON-encoded strings.
 
         The value of `None` will remove the metadata key from the interaction.
         This is distinct from using an empty string or a string containing the
@@ -452,7 +450,8 @@ def set_comment(self, key: str, value: Any | None) -> Self:  # noqa: ANN401
         # Warning
 
         This function will overwrite any existing comment with the same key. In
-        particular, the `text` key is used by `add_text_comment`.
+        particular, the `text` key is used by
+        [`add_text_comment`][add_text_comment].
         """
         if isinstance(value, str) or value is None:
             pact_ffi.set_comment(self._handle, key, value)
@@ -475,7 +474,7 @@ def add_text_comment(self, comment: str) -> Self:
 
         Internally, the comments are appended to an array under the `text`
         comment key. Care should be taken to ensure that conflicts are not
-        introduced by [`set_comment`][pact.interaction.Interaction.set_comment].
+        introduced by [`set_comment`][set_comment].
         """
         pact_ffi.add_text_comment(self._handle, comment)
         return self

src/pact/interaction/_http_interaction.py

@@ -32,8 +32,7 @@ class HttpInteraction(Interaction):
     HTTP interaction. As many elements are shared between the request and
     response, this class provides a common interface for both. The functions
     intelligently determine whether the element should be added to the request
-    or the response based on whether
-    [`will_respond_with`][pact.interaction.HttpInteraction.will_respond_with]
+    or the response based on whether [`will_respond_with`][will_respond_with]
     has been called.
 
     For example, the following two interactions are equivalent:
@@ -165,9 +164,8 @@ def with_header(
 
                 If `None`, then the function intelligently determines whether
                 the header should be added to the request or the response, based
-                on whether the
-                [`will_respond_with`][pact.interaction.HttpInteraction.will_respond_with]
-                method has been called.
+                on whether the [`will_respond_with`][will_respond_with] method
+                has been called.
         """
         interaction_part = self._parse_interaction_part(part)
         name_lower = name.lower()
@@ -204,10 +202,10 @@ def with_headers(
         -   Passing in an iterable of key-value tuples.
 
         -   Make multiple calls to this function or
-            [`with_header`][pact.interaction.HttpInteraction.with_header].
+            [`with_header`][with_header].
 
         See
-        [`with_header`][pact.interaction.HttpInteraction.with_header]
+        [`with_header`][with_header]
         for more information.
 
         Args:
@@ -220,9 +218,8 @@ def with_headers(
 
                 If `None`, then the function intelligently determines whether
                 the header should be added to the request or the response, based
-                on whether the
-                [`will_respond_with`][pact.interaction.HttpInteraction.will_respond_with]
-                method has been called.
+                on whether the [`will_respond_with`][will_respond_with] method
+                has been called.
         """
         if isinstance(headers, dict):
             headers = headers.items()
@@ -239,10 +236,9 @@ def set_header(
         r"""
         Add a header to the request.
 
-        Unlike
-        [`with_header`][pact.interaction.HttpInteraction.with_header], this
-        function does no additional processing of the header value. This is
-        useful for headers that contain a JSON object.
+        Unlike [`with_header`][with_header], this function does no additional
+        processing of the header value. This is useful for headers that contain
+        a JSON object.
 
         Args:
             name:
@@ -257,9 +253,8 @@ def set_header(
 
                 If `None`, then the function intelligently determines whether
                 the header should be added to the request or the response, based
-                on whether the
-                [`will_respond_with`][pact.interaction.HttpInteraction.will_respond_with]
-                method has been called.
+                on whether the [`will_respond_with`][will_respond_with] method
+                has been called.
         """
         pact_ffi.set_header(
             self._handle,
@@ -287,10 +282,9 @@ def set_headers(
         -   Passing in an iterable of key-value tuples.
 
         -   Make multiple calls to this function or
-            [`with_header`][pact.interaction.HttpInteraction.with_header].
+            [`with_header`][with_header].
 
-        See [`set_header`][pact.interaction.HttpInteraction.set_header] for
-        more information.
+        See [`set_header`][set_header] for more information.
 
         Args:
             headers:
@@ -302,8 +296,7 @@ def set_headers(
 
                 If `None`, then the function intelligently determines whether
                 the headers should be added to the request or the response,
-                based on whether the
-                [`will_respond_with`][pact.interaction.HttpInteraction.will_respond_with]
+                based on whether the [`will_respond_with`][will_respond_with]
                 method has been called.
         """
         if isinstance(headers, dict):
@@ -372,11 +365,9 @@ def with_query_parameters(
         -   Passing in an iterable of key-value tuples.
 
         -   Make multiple calls to this function or
-            [`with_query_parameter`][pact.interaction.HttpInteraction.with_query_parameter].
+            [`with_query_parameter`][with_query_parameter].
 
-        See
-        [`with_query_parameter`][pact.interaction.HttpInteraction.with_query_parameter]
-        for more information.
+        See [`with_query_parameter`][with_query_parameter] for more information.
 
         Args:
             parameters:
@@ -393,9 +384,8 @@ def will_respond_with(self, status: int) -> Self:
         Set the response status.
 
         Ideally, this function is called once all of the request information has
-        been set. This allows functions such as
-        [`with_header`][pact.interaction.HttpInteraction.with_header]
-        to intelligently determine whether this is a request or response header.
+        been set. This allows functions such as [`with_header`][with_header] to
+        intelligently determine whether this is a request or response header.
 
         Alternatively, the `part` argument can be used to explicitly specify
         whether the header should be added to the request or the response.

src/pact/interaction/_sync_message_interaction.py

@@ -18,7 +18,7 @@ class SyncMessageInteraction(Interaction):
     A synchronous message interaction.
 
     This class defines a synchronous message interaction between a consumer and
-    a provider. As with [`HttpInteraction`][pact.pact.HttpInteraction], it
+    a provider. As with [`HttpInteraction`][HttpInteraction], it
     defines a specific request that the consumer makes to the provider, and the
     response that the provider should return.
     """
@@ -29,8 +29,8 @@ def __init__(self, pact_handle: pact_ffi.PactHandle, description: str) -> None:
 
         This function should not be called directly. Instead, an
         AsyncMessageInteraction should be created using the
-        [`upon_receiving`][pact.Pact.upon_receiving] method of a
-        [`Pact`][pact.Pact] instance using the `"Sync"` interaction type.
+        [`upon_receiving`][Pact.upon_receiving] method of a
+        [`Pact`][Pact] instance using the `"Sync"` interaction type.
 
         Args:
             pact_handle:
@@ -67,9 +67,8 @@ def will_respond_with(self) -> Self:
 
         This method is a convenience method to separate the request and response
         parts of the interaction. This function is analogous to the
-        [`will_respond_with()`][pact.pact.HttpInteraction.will_respond_with]
-        method of the [`HttpInteraction`][pact.pact.HttpInteraction] class,
-        albeit more generic for synchronous message interactions.
+        [`HttpInteraction.will_respond_with()`][HttpInteraction.will_respond_with]
+        method, albeit more generic for synchronous message interactions.
 
         For example, the following two snippets are equivalent: