Doc fixes (#1241)

* Upgrade pydoctor and fix nexus docs

* Fix pydoctor warnings and raise warnings as errors when generating docs

* run formatter

Author: VegetarianOrc

pyproject.toml

@@ -44,7 +44,7 @@ dev = [
   "mypy-protobuf>=3.3.0,<4",
   "psutil>=5.9.3,<6",
   "pydocstyle>=6.3.0,<7",
-  "pydoctor>=24.11.1,<25",
+  "pydoctor>=25.10.1,<26",
   "pyright==1.1.403",
   "pytest~=7.4",
   "pytest-asyncio>=0.21,<0.22",
@@ -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/__init__.py

@@ -6,15 +6,28 @@
 See https://github.com/temporalio/sdk-python/tree/main#nexus
 """
 
-from ._decorators import workflow_run_operation as workflow_run_operation
-from ._operation_context import Info as Info
-from ._operation_context import LoggerAdapter as LoggerAdapter
-from ._operation_context import NexusCallback as NexusCallback
+from ._decorators import workflow_run_operation
 from ._operation_context import (
-    WorkflowRunOperationContext as WorkflowRunOperationContext,
+    Info,
+    LoggerAdapter,
+    NexusCallback,
+    WorkflowRunOperationContext,
+    client,
+    in_operation,
+    info,
+    logger,
+)
+from ._token import WorkflowHandle
+
+__all__ = (
+    "workflow_run_operation",
+    "Info",
+    "LoggerAdapter",
+    "NexusCallback",
+    "WorkflowRunOperationContext",
+    "client",
+    "in_operation",
+    "info",
+    "logger",
+    "WorkflowHandle",
 )
-from ._operation_context import client as client
-from ._operation_context import in_operation as in_operation
-from ._operation_context import info as info
-from ._operation_context import logger as logger
-from ._token import WorkflowHandle as WorkflowHandle

temporalio/nexus/_operation_context.py

@@ -23,8 +23,6 @@
 import temporalio.api.common.v1
 import temporalio.api.workflowservice.v1
 import temporalio.common
-from temporalio.nexus import _link_conversion
-from temporalio.nexus._token import WorkflowHandle
 from temporalio.types import (
     MethodAsyncNoParam,
     MethodAsyncSingleParam,
@@ -34,6 +32,13 @@
     SelfType,
 )
 
+from ._link_conversion import (
+    nexus_link_to_workflow_event,
+    workflow_event_to_nexus_link,
+    workflow_execution_started_event_link_from_workflow_handle,
+)
+from ._token import WorkflowHandle
+
 if TYPE_CHECKING:
     import temporalio.client
 
@@ -162,7 +167,7 @@ def _get_workflow_event_links(
     ) -> list[temporalio.api.common.v1.Link.WorkflowEvent]:
         event_links = []
         for inbound_link in self.nexus_context.inbound_links:
-            if link := _link_conversion.nexus_link_to_workflow_event(inbound_link):
+            if link := nexus_link_to_workflow_event(inbound_link):
                 event_links.append(link)
         return event_links
 
@@ -182,14 +187,13 @@ def _add_outbound_links(
                             wf_event_links.append(link.workflow_event)
             if not wf_event_links:
                 wf_event_links = [
-                    _link_conversion.workflow_execution_started_event_link_from_workflow_handle(
+                    workflow_execution_started_event_link_from_workflow_handle(
                         workflow_handle,
                         self.nexus_context.request_id,
                     )
                 ]
             self.nexus_context.outbound_links.extend(
-                _link_conversion.workflow_event_to_nexus_link(link)
-                for link in wf_event_links
+                workflow_event_to_nexus_link(link) for link in wf_event_links
             )
         except Exception as e:
             logger.warning(

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.
 
     """