Fix pydoctor warnings and raise warnings as errors when generating docs

Author: VegetarianOrc

pyproject.toml

@@ -158,6 +158,7 @@ intersphinx = [
   "https://docs.python.org/3/objects.inv",
   "https://googleapis.dev/python/protobuf/latest/objects.inv",
   "https://opentelemetry-python.readthedocs.io/en/latest/objects.inv",
+  "https://nexus-rpc.github.io/sdk-python/objects.inv",
 ]
 privacy = [
   "PRIVATE:temporalio.bridge",
@@ -177,6 +178,7 @@ privacy = [
 ]
 project-name = "Temporal Python"
 sidebar-expand-depth = 2
+warnings-as-errors = true
 
 [tool.pyright]
 enableTypeIgnoreComments = true

temporalio/activity.py

@@ -288,7 +288,7 @@ def wait_sync(self, timeout: Optional[float] = None) -> None:
 def client() -> Client:
     """Return a Temporal Client for use in the current activity.
 
-    The client is only available in `async def` activities.
+    The client is only available in ``async def`` activities.
 
     In tests it is not available automatically, but you can pass a client when creating a
     :py:class:`temporalio.testing.ActivityEnvironment`.

temporalio/common.py

@@ -1088,7 +1088,7 @@ def to_canonical_string(self) -> str:
     @staticmethod
     def from_canonical_string(canonical: str) -> WorkerDeploymentVersion:
         """Parse a version from a canonical string, which must be in the format
-        `<deployment_name>.<build_id>`. Deployment name must not have a `.` in it.
+        `<deployment_name>.<build_id>`. Deployment name must not have a ``.`` in it.
         """
         parts = canonical.split(".", maxsplit=1)
         if len(parts) != 2:

temporalio/contrib/openai_agents/workflow.py

@@ -60,11 +60,13 @@ def activity_as_tool(
     of inputs and outputs between the agent and the activity. Note that if you take a context,
     mutation will not be persisted, as the activity may not be running in the same location.
 
+    For undocumented arguments, refer to :py:mod:`workflow` and :py:meth:`start_activity`
+
     Args:
         fn: A Temporal activity function to convert to a tool.
         strict_json_schema: Whether the tool should follow a strict schema.
             See https://openai.github.io/openai-agents-python/ref/tool/#agents.tool.FunctionTool.strict_json_schema
-        For other arguments, refer to :py:mod:`workflow` :py:meth:`start_activity`
+
 
     Returns:
         An OpenAI agent tool that wraps the provided activity.
@@ -178,7 +180,7 @@ def nexus_operation_as_tool(
     of inputs and outputs between the agent and the operation.
 
     Args:
-        fn: A Nexus operation to convert into a tool.
+        operation: A Nexus operation to convert into a tool.
         service: The Nexus service class that contains the operation.
         endpoint: The Nexus endpoint to use for the operation.
         strict_json_schema: Whether the tool should follow a strict schema

temporalio/envconfig.py

@@ -184,7 +184,7 @@ class ClientConfigProfile:
     """Represents a client configuration profile.
 
     This class holds the configuration as loaded from a file or environment.
-    See `to_connect_config` to transform the profile to `ClientConnectConfig`,
+    See `to_client_connect_config` to transform the profile to `ClientConnectConfig`,
     which can be used to create a client.
 
     .. warning::
@@ -304,8 +304,8 @@ class ClientConfig:
     """Client configuration loaded from TOML and environment variables.
 
     This contains a mapping of profile names to client profiles. Use
-    `ClientConfigProfile.to_connect_config` to create a `ClientConnectConfig`
-    from a profile. See `load_profile` to load an individual profile.
+    `ClientConfigProfile.to_client_connect_config` to create a `ClientConnectConfig`
+    from a profile. See `ClientConfigProfile.load` to load an individual profile.
 
     .. warning::
         Experimental API.

temporalio/nexus/_operation_handlers.py

@@ -91,7 +91,7 @@ async def _cancel_workflow(
 
     Args:
         token: The token of the workflow to cancel. kwargs: Additional keyword arguments
-        to pass to the workflow cancel method.
+         to pass to the workflow cancel method.
     """
     try:
         nexus_workflow_handle = WorkflowHandle[Any].from_token(token)

temporalio/nexus/_util.py

@@ -39,7 +39,7 @@ def get_workflow_run_start_method_input_and_output_type_annotations(
 ]:
     """Return operation input and output types.
 
-    `start` must be a type-annotated start method that returns a
+    ``start`` must be a type-annotated start method that returns a
     :py:class:`temporalio.nexus.WorkflowHandle`.
     """
     input_type, output_type = _get_start_method_input_and_output_type_annotations(start)
@@ -125,7 +125,7 @@ def get_operation_factory(
     Optional[Callable[[Any], Any]],
     Optional[nexusrpc.Operation[Any, Any]],
 ]:
-    """Return the :py:class:`Operation` for the object along with the factory function.
+    """Return the :py:class:`nexusrpc.Operation` for the object along with the factory function.
 
     ``obj`` should be a decorated operation start method.
     """
@@ -145,7 +145,7 @@ def set_operation_factory(
     obj: Any,
     operation_factory: Callable[[Any], Any],
 ) -> None:
-    """Set the :py:class:`OperationHandler` factory for this object.
+    """Set the :py:class:`nexusrpc.handler.OperationHandler` factory for this object.
 
     ``obj`` should be an operation start method.
     """
@@ -158,7 +158,7 @@ def set_operation_factory(
 #
 # This file is licensed under the MIT License.
 def is_async_callable(obj: Any) -> bool:
-    """Return True if `obj` is an async callable.
+    """Return True if ``obj`` is an async callable.
 
     Supports partials of async callable class instances.
     """

temporalio/runtime.py

@@ -69,7 +69,7 @@ class Runtime:
     thread pool is created.
 
     Runtimes do not work across forks. Advanced users should consider using
-    :py:meth:`prevent_default` and `:py:meth`set_default` to ensure each
+    :py:meth:`prevent_default` and :py:meth:`set_default` to ensure each
     fork creates it's own runtime.
 
     """

temporalio/service.py

@@ -230,11 +230,8 @@ async def check_health(
         metadata: Mapping[str, Union[str, bytes]] = {},
         timeout: Optional[timedelta] = None,
     ) -> bool:
-        """Check whether the WorkflowService is up.
-
-        In addition to accepting which service to check health on, this accepts
-        some of the same parameters as other RPC calls. See
-        :py:meth:`ServiceCall.__call__`.
+        """Check whether the provided service is up. If no service is specified,
+         the WorkflowService is used.
 
         Returns:
             True when available, false if the server is running but the service

temporalio/worker/_interceptor.py

@@ -469,5 +469,5 @@ def start_local_activity(
     async def start_nexus_operation(
         self, input: StartNexusOperationInput[InputT, OutputT]
     ) -> temporalio.workflow.NexusOperationHandle[OutputT]:
-        """Called for every :py:func:`temporalio.workflow.start_nexus_operation` call."""
+        """Called for every :py:func:`temporalio.workflow.NexusClient.start_operation` call."""
         return await self.next.start_nexus_operation(input)