Merge pull request #1022 from opsmill/pog-documentation-formatting

Fix docstring formatting

Author: ogenstad

docs/docs/infrahubctl/infrahubctl-graphql.mdx

@@ -37,7 +37,7 @@ $ infrahubctl graphql export-schema [OPTIONS]
 
 ## `infrahubctl graphql generate-return-types`
 
-Create Pydantic Models for GraphQL query return types
+Create Pydantic Models for GraphQL query return types.
 
 **Usage**:
 

docs/docs/infrahubctl/infrahubctl-validate.mdx

@@ -21,7 +21,7 @@ $ infrahubctl validate [OPTIONS] COMMAND [ARGS]...
 
 ## `infrahubctl validate graphql-query`
 
-Validate the format of a GraphQL Query stored locally by executing it on a remote GraphQL endpoint
+Validate the format of a GraphQL Query stored locally by executing it on a remote GraphQL endpoint.
 
 **Usage**:
 
@@ -44,7 +44,7 @@ $ infrahubctl validate graphql-query [OPTIONS] QUERY [VARIABLES]...
 
 ## `infrahubctl validate schema`
 
-Validate the format of a schema file either in JSON or YAML
+Validate the format of a schema file either in JSON or YAML.
 
 **Usage**:
 

docs/docs/python-sdk/sdk_ref/infrahub_sdk/client.mdx

@@ -101,15 +101,15 @@ Return the Infrahub version.
 get_user(self) -> dict
 ```
 
-Return user information
+Return user information.
 
 #### `get_user_permissions`
 
 ```python
 get_user_permissions(self) -> dict
 ```
 
-Return user permissions
+Return user permissions.
 
 #### `count`
 
@@ -140,7 +140,7 @@ all(self, kind: str, at: Timestamp | None = ..., branch: str | None = ..., timeo
 all(self, kind: str | type[SchemaType], at: Timestamp | None = None, branch: str | None = None, timeout: int | None = None, populate_store: bool = True, offset: int | None = None, limit: int | None = None, include: list[str] | None = None, exclude: list[str] | None = None, fragment: bool = False, prefetch_relationships: bool = False, property: bool = False, parallel: bool = False, order: Order | None = None, include_metadata: bool = False, query_name: str | None = None) -> list[InfrahubNode] | list[SchemaType]
 ```
 
-Retrieve all nodes of a given kind
+Retrieve all nodes of a given kind.
 
 **Args:**
 
@@ -219,7 +219,7 @@ Retrieve nodes of a given kind based on provided filters.
 clone(self, branch: str | None = None) -> InfrahubClient
 ```
 
-Return a cloned version of the client using the same configuration
+Return a cloned version of the client using the same configuration.
 
 #### `execute_graphql`
 
@@ -228,6 +228,7 @@ execute_graphql(self, query: str, variables: dict | None = None, branch_name: st
 ```
 
 Execute a GraphQL query (or mutation).
+
 If retry_on_failure is True, the query will retry until the server becomes reachable.
 
 **Args:**
@@ -238,6 +239,10 @@ If retry_on_failure is True, the query will retry until the server becomes reach
 - `at`: Time when the query should be executed. Defaults to None.
 - `timeout`: Timeout in second for the query. Defaults to None.
 
+**Returns:**
+
+- The GraphQL data payload (response["data"]).
+
 **Raises:**
 
 - `GraphQLError`: When the GraphQL response contains errors.
@@ -246,10 +251,6 @@ If retry_on_failure is True, the query will retry until the server becomes reach
 - `URLNotFoundError`: If the server returns a 404 response.
 - `Error`: If the response is unexpectedly missing.
 
-**Returns:**
-
-- The GraphQL data payload (response["data"]).
-
 #### `refresh_login`
 
 ```python
@@ -405,10 +406,11 @@ repository_update_commit(self, branch_name: str, repository_id: str, commit: str
 convert_object_type(self, node_id: str, target_kind: str, branch: str | None = None, fields_mapping: dict[str, ConversionFieldInput] | None = None) -> InfrahubNode
 ```
 
-Convert a given node to another kind on a given branch. `fields_mapping` keys are target fields names
-and its values indicate how to fill in these fields. Any mandatory field not having an equivalent field
-in the source kind should be specified in this mapping. See https://docs.infrahub.app/guides/object-conversion
-for more information.
+Convert a given node to another kind on a given branch.
+
+`fields_mapping` keys are target fields names and its values indicate how to fill in these fields.
+Any mandatory field not having an equivalent field in the source kind should be specified in this
+mapping. See https://docs.infrahub.app/guides/object-conversion for more information.
 
 ### `InfrahubClientSync`
 
@@ -502,23 +504,23 @@ Return the Infrahub version.
 get_user(self) -> dict
 ```
 
-Return user information
+Return user information.
 
 #### `get_user_permissions`
 
 ```python
 get_user_permissions(self) -> dict
 ```
 
-Return user permissions
+Return user permissions.
 
 #### `clone`
 
 ```python
 clone(self, branch: str | None = None) -> InfrahubClientSync
 ```
 
-Return a cloned version of the client using the same configuration
+Return a cloned version of the client using the same configuration.
 
 #### `execute_graphql`
 
@@ -527,6 +529,7 @@ execute_graphql(self, query: str, variables: dict | None = None, branch_name: st
 ```
 
 Execute a GraphQL query (or mutation).
+
 If retry_on_failure is True, the query will retry until the server becomes reachable.
 
 **Args:**
@@ -537,6 +540,10 @@ If retry_on_failure is True, the query will retry until the server becomes reach
 - `at`: Time when the query should be executed. Defaults to None.
 - `timeout`: Timeout in second for the query. Defaults to None.
 
+**Returns:**
+
+- The GraphQL data payload (`response["data"]`).
+
 **Raises:**
 
 - `GraphQLError`: When the GraphQL response contains errors.
@@ -545,10 +552,6 @@ If retry_on_failure is True, the query will retry until the server becomes reach
 - `URLNotFoundError`: If the server returns a 404 response.
 - `Error`: If the response is unexpectedly missing.
 
-**Returns:**
-
-- The GraphQL data payload (`response["data"]`).
-
 #### `count`
 
 ```python
@@ -578,7 +581,7 @@ all(self, kind: str, at: Timestamp | None = ..., branch: str | None = ..., timeo
 all(self, kind: str | type[SchemaTypeSync], at: Timestamp | None = None, branch: str | None = None, timeout: int | None = None, populate_store: bool = True, offset: int | None = None, limit: int | None = None, include: list[str] | None = None, exclude: list[str] | None = None, fragment: bool = False, prefetch_relationships: bool = False, property: bool = False, parallel: bool = False, order: Order | None = None, include_metadata: bool = False, query_name: str | None = None) -> list[InfrahubNodeSync] | list[SchemaTypeSync]
 ```
 
-Retrieve all nodes of a given kind
+Retrieve all nodes of a given kind.
 
 **Args:**
 
@@ -811,10 +814,11 @@ login(self, refresh: bool = False) -> None
 convert_object_type(self, node_id: str, target_kind: str, branch: str | None = None, fields_mapping: dict[str, ConversionFieldInput] | None = None) -> InfrahubNodeSync
 ```
 
-Convert a given node to another kind on a given branch. `fields_mapping` keys are target fields names
-and its values indicate how to fill in these fields. Any mandatory field not having an equivalent field
-in the source kind should be specified in this mapping. See https://docs.infrahub.app/guides/object-conversion
-for more information.
+Convert a given node to another kind on a given branch.
+
+`fields_mapping` keys are target fields names and its values indicate how to fill in these fields.
+Any mandatory field not having an equivalent field in the source kind should be specified in this
+mapping. See https://docs.infrahub.app/guides/object-conversion for more information.
 
 ### `ProcessRelationsNode`
 
@@ -826,7 +830,7 @@ for more information.
 
 ### `BaseClient`
 
-Base class for InfrahubClient and InfrahubClientSync
+Base class for InfrahubClient and InfrahubClientSync.
 
 **Methods:**
 

docs/docs/python-sdk/sdk_ref/infrahub_sdk/node/node.mdx

@@ -626,7 +626,7 @@ caller re-fetches the node first.
 
 ### `InfrahubNodeBase`
 
-Base class for InfrahubNode and InfrahubNodeSync
+Base class for InfrahubNode and InfrahubNodeSync.
 
 **Methods:**
 

docs/docs/python-sdk/sdk_ref/infrahub_sdk/node/relationship.mdx

@@ -9,7 +9,7 @@ sidebarTitle: relationship
 
 ### `RelationshipManagerBase`
 
-Base class for RelationshipManager and RelationshipManagerSync
+Base class for RelationshipManager and RelationshipManagerSync.
 
 **Methods:**
 

docs/docs_generation/content_gen_methods/mdx/mdx_collapsed_overload_section.py

@@ -8,10 +8,10 @@
 
 @dataclass
 class CollapsedOverloadSection(ASection):
-    """Collapses a group of overloaded method sections into one primary entry
-    followed by a collapsible ``<details>`` block with the remaining overloads.
+    """Collapse a group of overloaded method sections into a primary entry plus a details block.
 
-    The *primary* overload is the one with the most parameters (excluding
+    The remaining overloads are placed inside a collapsible ``<details>`` block following the
+    primary entry. The *primary* overload is the one with the most parameters (excluding
     ``self``).  On ties, the first in source order wins.
 
     Example::

infrahub_sdk/analyzer.py

@@ -99,12 +99,12 @@ def variables(self) -> list[GraphQLQueryVariable]:
         return response
 
     async def calculate_depth(self) -> int:
-        """Number of nested levels in the query"""
+        """Number of nested levels in the query."""
         fields = await self.get_fields()
         return calculate_dict_depth(data=fields)
 
     async def calculate_height(self) -> int:
-        """Total number of fields requested in the query"""
+        """Total number of fields requested in the query."""
         fields = await self.get_fields()
         return calculate_dict_height(data=fields)
 

infrahub_sdk/checks.py

@@ -147,11 +147,12 @@ def validate(self, data: dict) -> None:
         """Code to validate the status of this check."""
 
     async def collect_data(self) -> dict:
-        """Query the result of the GraphQL Query defined in self.query and return the result"""
+        """Query the result of the GraphQL Query defined in self.query and return the result."""
         return await self.client.query_gql_query(name=self.query, branch_name=self.branch_name, variables=self.params)
 
     async def run(self, data: dict | None = None) -> bool:
         """Execute the check after collecting the data from the GraphQL query.
+
         The result of the check is determined based on the presence or not of ERROR log messages.
         """
         if not data: