docs: Show correct accessors in the documentation (#2563)

Co-authored-by: Håkon V. Treider <haakonvt@gmail.com>

Author: MortGron

.gitignore

@@ -62,3 +62,6 @@ my_file.txt
 *.env
 .envrc
 .ropeproject
+
+# docs
+docs/source/generated/

cognite/client/_api/agents/agents.py

@@ -37,7 +37,7 @@ async def upsert(self, agents: AgentUpsert) -> Agent: ...
     async def upsert(self, agents: Sequence[AgentUpsert]) -> AgentList: ...
 
     async def upsert(self, agents: AgentUpsert | Sequence[AgentUpsert]) -> Agent | AgentList:
-        """`Create or update (upsert) one or more agents. <https://api-docs.cognite.com/20230101-beta/tag/Agents/operation/main_ai_agents_post/>`_
+        """`Create or update (upsert) one or more agents <https://api-docs.cognite.com/20230101-beta/tag/Agents/operation/main_ai_agents_post/>`_.
 
         Args:
             agents (AgentUpsert | Sequence[AgentUpsert]): Agent or list of agents to create or update.
@@ -180,7 +180,7 @@ async def retrieve(self, external_ids: SequenceNotStr[str], ignore_unknown_ids:
     async def retrieve(
         self, external_ids: str | SequenceNotStr[str], ignore_unknown_ids: bool = False
     ) -> Agent | AgentList | None:
-        """`Retrieve one or more agents by external ID. <https://api-docs.cognite.com/20230101-beta/tag/Agents/operation/get_agents_by_ids_ai_agents_byids_post/>`_
+        """`Retrieve one or more agents by external ID <https://api-docs.cognite.com/20230101-beta/tag/Agents/operation/get_agents_by_ids_ai_agents_byids_post/>`_.
 
         Args:
             external_ids (str | SequenceNotStr[str]): The external id of the agent(s) to retrieve.
@@ -212,7 +212,7 @@ async def retrieve(
         )
 
     async def delete(self, external_ids: str | SequenceNotStr[str], ignore_unknown_ids: bool = False) -> None:
-        """`Delete one or more agents. <https://api-docs.cognite.com/20230101-beta/tag/Agents/operation/agent_delete_ai_agents_delete_post/>`_
+        """`Delete one or more agents <https://api-docs.cognite.com/20230101-beta/tag/Agents/operation/agent_delete_ai_agents_delete_post/>`_.
 
         Args:
             external_ids (str | SequenceNotStr[str]): External ID of the agent or a list of external ids.
@@ -236,7 +236,7 @@ async def delete(self, external_ids: str | SequenceNotStr[str], ignore_unknown_i
         )
 
     async def list(self) -> AgentList:  # The API does not yet support limit or pagination
-        """`List agents. <https://api-docs.cognite.com/20230101-beta/tag/Agents/operation/agent_list_ai_agents_get/>`_
+        """`List agents <https://api-docs.cognite.com/20230101-beta/tag/Agents/operation/agent_list_ai_agents_get/>`_.
 
         Returns:
             AgentList: The list of agents.
@@ -262,7 +262,7 @@ async def chat(
         cursor: str | None = None,
         actions: Sequence[Action] | None = None,
     ) -> AgentChatResponse:
-        """`Chat with an agent. <https://api-docs.cognite.com/20230101-beta/tag/Agents/operation/agent_session_ai_agents_chat_post/>`_
+        """`Chat with an agent <https://api-docs.cognite.com/20230101-beta/tag/Agents/operation/agent_session_ai_agents_chat_post/>`_.
 
         Given a user query, the Atlas AI agent responds by reasoning and using the tools associated with it.
         Users can ensure conversation continuity by including the cursor from the previous response in subsequent requests.

cognite/client/_api/ai/tools/documents.py

@@ -18,7 +18,7 @@ async def summarize(
         external_id: str | None = None,
         instance_id: NodeId | None = None,
     ) -> Summary:
-        """`Summarize a document using a Large Language Model. <https://api-docs.cognite.com/20230101/tag/Document-AI/operation/document_questioning_ai_tools_documents_ask_post>`_
+        """`Summarize a document using a Large Language Model <https://api-docs.cognite.com/20230101/tag/Document-AI/operation/document_questioning_ai_tools_documents_ask_post>`_.
 
         Note:
             Currently only supports summarizing a single document at a time, but
@@ -78,7 +78,7 @@ async def ask_question(
         additional_context: str | None = None,
         ignore_unknown_ids: bool = False,
     ) -> Answer:
-        """`Ask a question about one or more documents using a Large Language Model. <https://api-docs.cognite.com/20230101/tag/Document-AI/operation/documents_summary_api_v1_projects__projectName__ai_tools_documents_summarize_post>`_
+        """`Ask a question about one or more documents using a Large Language Model <https://api-docs.cognite.com/20230101/tag/Document-AI/operation/documents_summary_api_v1_projects__projectName__ai_tools_documents_summarize_post>`_.
 
         Supports up to 100 documents at a time.
 

cognite/client/_api/annotations.py

@@ -39,7 +39,7 @@ async def create(self, annotations: Sequence[Annotation | AnnotationWrite]) -> A
     async def create(
         self, annotations: Annotation | AnnotationWrite | Sequence[Annotation | AnnotationWrite]
     ) -> Annotation | AnnotationList:
-        """`Create annotations <https://api-docs.cognite.com/20230101/tag/Annotations/operation/annotationsCreate>`_
+        """`Create annotations <https://api-docs.cognite.com/20230101/tag/Annotations/operation/annotationsCreate>`_.
 
         Args:
             annotations (Annotation | AnnotationWrite | Sequence[Annotation | AnnotationWrite]): Annotation(s) to create
@@ -66,7 +66,7 @@ async def suggest(self, annotations: Sequence[Annotation] | Sequence[AnnotationW
     async def suggest(
         self, annotations: Annotation | AnnotationWrite | Sequence[Annotation] | Sequence[AnnotationWrite]
     ) -> Annotation | AnnotationList:
-        """`Suggest annotations <https://api-docs.cognite.com/20230101/tag/Annotations/operation/annotationsSuggest>`_
+        """`Suggest annotations <https://api-docs.cognite.com/20230101/tag/Annotations/operation/annotationsSuggest>`_.
 
         Args:
             annotations (Annotation | AnnotationWrite | Sequence[Annotation] | Sequence[AnnotationWrite]): annotation(s) to suggest. They must have status set to "suggested".
@@ -138,7 +138,7 @@ async def update(
         | Sequence[Annotation | AnnotationWrite | AnnotationUpdate],
         mode: Literal["replace_ignore_null", "patch", "replace"] = "replace_ignore_null",
     ) -> Annotation | AnnotationList:
-        """`Update annotations <https://api-docs.cognite.com/20230101/tag/Annotations/operation/annotationsUpdate>`_
+        """`Update annotations <https://api-docs.cognite.com/20230101/tag/Annotations/operation/annotationsUpdate>`_.
 
         Args:
             item (Annotation | AnnotationWrite | AnnotationUpdate | Sequence[Annotation | AnnotationWrite | AnnotationUpdate]): Annotation or list of annotations to update (or patch or list of patches to apply)
@@ -151,15 +151,15 @@ async def update(
         )
 
     async def delete(self, id: int | Sequence[int]) -> None:
-        """`Delete annotations <https://api-docs.cognite.com/20230101/tag/Annotations/operation/annotationsDelete>`_
+        """`Delete annotations <https://api-docs.cognite.com/20230101/tag/Annotations/operation/annotationsDelete>`_.
 
         Args:
             id (int | Sequence[int]): ID or list of IDs to be deleted
         """
         await self._delete_multiple(identifiers=IdentifierSequence.load(ids=id), wrap_ids=True)
 
     async def retrieve_multiple(self, ids: Sequence[int]) -> AnnotationList:
-        """`Retrieve annotations by IDs <https://api-docs.cognite.com/20230101/tag/Annotations/operation/annotationsByids>`_`
+        """`Retrieve annotations by IDs <https://api-docs.cognite.com/20230101/tag/Annotations/operation/annotationsByids>`_.
 
         Args:
             ids (Sequence[int]): list of IDs to be retrieved
@@ -171,7 +171,7 @@ async def retrieve_multiple(self, ids: Sequence[int]) -> AnnotationList:
         return await self._retrieve_multiple(list_cls=AnnotationList, resource_cls=Annotation, identifiers=identifiers)
 
     async def retrieve(self, id: int) -> Annotation | None:
-        """`Retrieve an annotation by id <https://api-docs.cognite.com/20230101/tag/Annotations/operation/annotationsGet>`_
+        """`Retrieve an annotation by id <https://api-docs.cognite.com/20230101/tag/Annotations/operation/annotationsGet>`_.
 
         Args:
             id (int): id of the annotation to be retrieved
@@ -219,7 +219,7 @@ async def reverse_lookup(
         )
 
     async def list(self, filter: AnnotationFilter | dict, limit: int | None = DEFAULT_LIMIT_READ) -> AnnotationList:
-        """`List annotations. <https://api-docs.cognite.com/20230101/tag/Annotations/operation/annotationsFilter>`_
+        """`List annotations <https://api-docs.cognite.com/20230101/tag/Annotations/operation/annotationsFilter>`_.
 
         Note:
             Passing a filter with both 'annotated_resource_type' and 'annotated_resource_ids' is always required.

cognite/client/_api/assets.py

@@ -210,7 +210,7 @@ async def __call__(
             yield item
 
     async def retrieve(self, id: int | None = None, external_id: str | None = None) -> Asset | None:
-        """`Retrieve a single asset by id. <https://api-docs.cognite.com/20230101/tag/Assets/operation/getAsset>`_
+        """`Retrieve a single asset by id <https://api-docs.cognite.com/20230101/tag/Assets/operation/getAsset>`_.
 
         Args:
             id (int | None): ID
@@ -241,7 +241,7 @@ async def retrieve_multiple(
         external_ids: SequenceNotStr[str] | None = None,
         ignore_unknown_ids: bool = False,
     ) -> AssetList:
-        """`Retrieve multiple assets by id. <https://api-docs.cognite.com/20230101/tag/Assets/operation/byIdsAssets>`_
+        """`Retrieve multiple assets by id <https://api-docs.cognite.com/20230101/tag/Assets/operation/byIdsAssets>`_.
 
         Args:
             ids (Sequence[int] | None): IDs
@@ -277,7 +277,7 @@ async def aggregate_count(
         advanced_filter: Filter | dict[str, Any] | None = None,
         filter: AssetFilter | dict[str, Any] | None = None,
     ) -> int:
-        """`Count of assets matching the specified filters. <https://api-docs.cognite.com/20230101/tag/Assets/operation/aggregateAssets>`_
+        """`Count of assets matching the specified filters <https://api-docs.cognite.com/20230101/tag/Assets/operation/aggregateAssets>`_.
 
         Args:
             property (AssetPropertyLike | None): If specified, get an approximate number of asset with a specific property (property is not null) and matching the filters.
@@ -319,7 +319,7 @@ async def aggregate_cardinality_values(
         aggregate_filter: AggregationFilter | dict[str, Any] | None = None,
         filter: AssetFilter | dict[str, Any] | None = None,
     ) -> int:
-        """`Find approximate property count for assets. <https://api-docs.cognite.com/20230101/tag/Assets/operation/aggregateAssets>`_
+        """`Find approximate property count for assets <https://api-docs.cognite.com/20230101/tag/Assets/operation/aggregateAssets>`_.
 
         Args:
             property (AssetPropertyLike): The property to count the cardinality of.
@@ -364,7 +364,7 @@ async def aggregate_cardinality_properties(
         aggregate_filter: AggregationFilter | dict[str, Any] | None = None,
         filter: AssetFilter | dict[str, Any] | None = None,
     ) -> int:
-        """`Find approximate paths count for assets.  <https://api-docs.cognite.com/20230101/tag/Assets/operation/aggregateAssets>`_
+        """`Find approximate paths count for assets <https://api-docs.cognite.com/20230101/tag/Assets/operation/aggregateAssets>`_.
 
         Args:
             path (AssetPropertyLike): The scope in every document to aggregate properties. The only value allowed now is ["metadata"].
@@ -401,7 +401,7 @@ async def aggregate_unique_values(
         aggregate_filter: AggregationFilter | dict[str, Any] | None = None,
         filter: AssetFilter | dict[str, Any] | None = None,
     ) -> UniqueResultList:
-        """`Get unique properties with counts for assets. <https://api-docs.cognite.com/20230101/tag/Assets/operation/aggregateAssets>`_
+        """`Get unique properties with counts for assets <https://api-docs.cognite.com/20230101/tag/Assets/operation/aggregateAssets>`_.
 
         Note:
             In the case of text fields, the values are aggregated in a case-insensitive manner.
@@ -476,7 +476,7 @@ async def aggregate_unique_properties(
         aggregate_filter: AggregationFilter | dict[str, Any] | None = None,
         filter: AssetFilter | dict[str, Any] | None = None,
     ) -> UniqueResultList:
-        """`Get unique paths with counts for assets. <https://api-docs.cognite.com/20230101/tag/Assets/operation/aggregateAssets>`_
+        """`Get unique paths with counts for assets <https://api-docs.cognite.com/20230101/tag/Assets/operation/aggregateAssets>`_.
 
         Note:
             In the case of text fields, the values are aggregated in a case-insensitive manner.
@@ -517,7 +517,7 @@ async def create(self, asset: Sequence[Asset] | Sequence[AssetWrite]) -> AssetLi
     async def create(self, asset: Asset | AssetWrite) -> Asset: ...
 
     async def create(self, asset: Asset | AssetWrite | Sequence[Asset] | Sequence[AssetWrite]) -> Asset | AssetList:
-        """`Create one or more assets. <https://api-docs.cognite.com/20230101/tag/Assets/operation/createAssets>`_
+        """`Create one or more assets <https://api-docs.cognite.com/20230101/tag/Assets/operation/createAssets>`_.
 
         You can create an arbitrary number of assets, and the SDK will split the request into multiple requests.
         When specifying parent-child relation between assets using `parentExternalId` the link will be resvoled into an internal ID and stored as `parentId`.
@@ -692,7 +692,7 @@ async def delete(
         recursive: bool = False,
         ignore_unknown_ids: bool = False,
     ) -> None:
-        """`Delete one or more assets <https://api-docs.cognite.com/20230101/tag/Assets/operation/deleteAssets>`_
+        """`Delete one or more assets <https://api-docs.cognite.com/20230101/tag/Assets/operation/deleteAssets>`_.
 
         Args:
             id (int | Sequence[int] | None): Id or list of ids
@@ -734,7 +734,8 @@ async def update(
         item: Asset | AssetWrite | AssetUpdate | Sequence[Asset | AssetWrite | AssetUpdate],
         mode: Literal["replace_ignore_null", "patch", "replace"] = "replace_ignore_null",
     ) -> Asset | AssetList:
-        """`Update one or more assets <https://api-docs.cognite.com/20230101/tag/Assets/operation/updateAssets>`_
+        """`Update one or more assets <https://api-docs.cognite.com/20230101/tag/Assets/operation/updateAssets>`_.
+
         Labels can be added, removed or replaced (set). Note that set operation deletes all the existing labels and adds the new specified labels.
 
         Args:
@@ -804,6 +805,7 @@ async def upsert(
         self, item: Asset | AssetWrite | Sequence[Asset | AssetWrite], mode: Literal["patch", "replace"] = "patch"
     ) -> Asset | AssetList:
         """Upsert assets, i.e., update if it exists, and create if it does not exist.
+
             Note this is a convenience method that handles the upserting for you by first calling update on all items,
             and if any of them fail because they do not exist, it will create them instead.
 
@@ -851,7 +853,8 @@ async def search(
         filter: AssetFilter | dict[str, Any] | None = None,
         limit: int = DEFAULT_LIMIT_READ,
     ) -> AssetList:
-        """`Search for assets <https://api-docs.cognite.com/20230101/tag/Assets/operation/searchAssets>`_
+        """`Search for assets <https://api-docs.cognite.com/20230101/tag/Assets/operation/searchAssets>`_.
+
         Primarily meant for human-centric use-cases and data exploration, not for programs, since matching and ordering may change over time. Use the `list` function if stable or exact matches are required.
 
         Args:
@@ -961,7 +964,7 @@ async def list(
         advanced_filter: Filter | dict[str, Any] | None = None,
         sort: SortSpec | list[SortSpec] | None = None,
     ) -> AssetList:
-        """`List assets <https://api-docs.cognite.com/20230101/tag/Assets/operation/listAssets>`_
+        """`List assets <https://api-docs.cognite.com/20230101/tag/Assets/operation/listAssets>`_.
 
         Args:
             name (str | None): Name of asset. Often referred to as tag.

cognite/client/_api/data_modeling/containers.py

@@ -101,7 +101,7 @@ async def retrieve(self, ids: Sequence[ContainerIdentifier]) -> ContainerList: .
     async def retrieve(
         self, ids: ContainerIdentifier | Sequence[ContainerIdentifier]
     ) -> Container | ContainerList | None:
-        """`Retrieve one or more container by id(s). <https://api-docs.cognite.com/20230101/tag/Containers/operation/byExternalIdsContainers>`_
+        """`Retrieve one or more container by id(s) <https://api-docs.cognite.com/20230101/tag/Containers/operation/byExternalIdsContainers>`_.
 
         Args:
             ids (ContainerIdentifier | Sequence[ContainerIdentifier]): Identifier for container(s).
@@ -132,7 +132,7 @@ async def retrieve(
         )
 
     async def delete(self, ids: ContainerIdentifier | Sequence[ContainerIdentifier]) -> list[ContainerId]:
-        """`Delete one or more containers <https://api-docs.cognite.com/20230101/tag/Containers/operation/deleteContainers>`_
+        """`Delete one or more containers <https://api-docs.cognite.com/20230101/tag/Containers/operation/deleteContainers>`_.
 
         Args:
             ids (ContainerIdentifier | Sequence[ContainerIdentifier]): The container identifier(s).
@@ -159,7 +159,7 @@ async def delete(self, ids: ContainerIdentifier | Sequence[ContainerIdentifier])
         return [ContainerId(space=item["space"], external_id=item["externalId"]) for item in deleted_containers]
 
     async def delete_constraints(self, ids: Sequence[ConstraintIdentifier]) -> list[ConstraintIdentifier]:
-        """`Delete one or more constraints <https://api-docs.cognite.com/20230101/tag/Containers/operation/deleteContainerConstraints>`_
+        """`Delete one or more constraints <https://api-docs.cognite.com/20230101/tag/Containers/operation/deleteContainerConstraints>`_.
 
         Args:
             ids (Sequence[ConstraintIdentifier]): The constraint identifier(s).
@@ -179,7 +179,7 @@ async def delete_constraints(self, ids: Sequence[ConstraintIdentifier]) -> list[
         return await self._delete_constraints_or_indexes(ids, "constraints")
 
     async def delete_indexes(self, ids: Sequence[IndexIdentifier]) -> list[IndexIdentifier]:
-        """`Delete one or more indexes <https://api-docs.cognite.com/20230101/tag/Containers/operation/deleteContainerIndexes>`_
+        """`Delete one or more indexes <https://api-docs.cognite.com/20230101/tag/Containers/operation/deleteContainerIndexes>`_.
 
         Args:
             ids (Sequence[IndexIdentifier]): The index identifier(s).
@@ -227,7 +227,7 @@ async def list(
         limit: int | None = DATA_MODELING_DEFAULT_LIMIT_READ,
         include_global: bool = False,
     ) -> ContainerList:
-        """`List containers <https://api-docs.cognite.com/20230101/tag/Containers/operation/listContainers>`_
+        """`List containers <https://api-docs.cognite.com/20230101/tag/Containers/operation/listContainers>`_.
 
         Args:
             space (str | None): The space to query
@@ -273,7 +273,7 @@ async def apply(self, container: Sequence[ContainerApply]) -> ContainerList: ...
     async def apply(self, container: ContainerApply) -> Container: ...
 
     async def apply(self, container: ContainerApply | Sequence[ContainerApply]) -> Container | ContainerList:
-        """`Add or update (upsert) containers. <https://api-docs.cognite.com/20230101/tag/Containers/operation/ApplyContainers>`_
+        """`Add or update (upsert) containers <https://api-docs.cognite.com/20230101/tag/Containers/operation/ApplyContainers>`_.
 
         Args:
             container (ContainerApply | Sequence[ContainerApply]): Container(s) to create or update.