Add documentation

Author: dgarros

.vale/styles/Infrahub/branded-terms-case-swap.yml

@@ -13,7 +13,6 @@ swap:
   (?:[Gg]itlab): GitLab
   (?:gitpod): GitPod
   (?:grafana): Grafana
-  (?:[^/][Gg]raphql): GraphQL
   (?:[Ii]nflux[Dd]b): InfluxDB
   infrahub(?:\s|$): Infrahub
   (?:jinja2): Jinja2

docs/docs/infrahubctl/infrahubctl-graphql.mdx

@@ -0,0 +1,56 @@
+# `infrahubctl graphql`
+
+Various GraphQL related commands.
+
+**Usage**:
+
+```console
+$ infrahubctl graphql [OPTIONS] COMMAND [ARGS]...
+```
+
+**Options**:
+
+* `--install-completion`: Install completion for the current shell.
+* `--show-completion`: Show completion for the current shell, to copy it or customize the installation.
+* `--help`: Show this message and exit.
+
+**Commands**:
+
+* `export-schema`: Export the GraphQL schema to a file.
+* `generate-return-types`: Create Pydantic Models for GraphQL query...
+
+## `infrahubctl graphql export-schema`
+
+Export the GraphQL schema to a file.
+
+**Usage**:
+
+```console
+$ infrahubctl graphql export-schema [OPTIONS]
+```
+
+**Options**:
+
+* `--destination PATH`: Path to the GraphQL schema file.  [default: schema.graphql]
+* `--config-file TEXT`: [env var: INFRAHUBCTL_CONFIG; default: infrahubctl.toml]
+* `--help`: Show this message and exit.
+
+## `infrahubctl graphql generate-return-types`
+
+Create Pydantic Models for GraphQL query return types
+
+**Usage**:
+
+```console
+$ infrahubctl graphql generate-return-types [OPTIONS] [QUERY]
+```
+
+**Arguments**:
+
+* `[QUERY]`: Location of the GraphQL query file(s).  [default: /Users/damien/projects/infrahub-sdk-python-pink]
+
+**Options**:
+
+* `--schema PATH`: Path to the GraphQL schema file.  [default: schema.graphql]
+* `--config-file TEXT`: [env var: INFRAHUBCTL_CONFIG; default: infrahubctl.toml]
+* `--help`: Show this message and exit.

docs/docs/python-sdk/guides/python-typing.mdx

@@ -101,3 +101,51 @@ my_object = client.get(MyOwnObject, name__value="example")
 ```
 
 > if you don't have your own Python module, it's possible to use relative path by having the `procotols.py` in the same directory as your script/transform/generator
+
+## Generating Pydantic models from GraphQL queries
+
+When working with GraphQL queries, you can generate type-safe Pydantic models that correspond to your query return types. This provides excellent type safety and IDE support for your GraphQL operations.
+
+### Why use generated return types?
+
+Generated Pydantic models from GraphQL queries offer several important benefits:
+
+- **Type Safety**: Catch type errors at development time instead of runtime
+- **IDE Support**: Get autocomplete, type hints, and better IntelliSense in your IDE  
+- **Documentation**: Generated models serve as living documentation of your GraphQL API
+- **Validation**: Automatic validation of query responses against the expected schema
+
+### Generating return types
+
+Use the `infrahubctl graphql generate-return-types` command to create Pydantic models from your GraphQL queries:
+
+```shell
+# Generate models for queries in current directory
+infrahubctl graphql generate-return-types
+
+# Generate models for specific query files
+infrahubctl graphql generate-return-types queries/get_devices.gql
+```
+
+> You can also export the GraphQL schema first using the `infrahubctl graphql export-schema` command:
+
+### Example workflow
+
+1. **Create your GraphQL queries** in `.gql` files:
+
+2. **Generate the Pydantic models**:
+
+   ```shell
+   infrahubctl graphql generate-return-types queries/
+   ```
+
+   The command will generate the Python file per query based on the name of the query.
+
+3. **Use the generated models** in your Python code
+
+   ```python
+   from .queries.get_devices import GetDevicesQuery
+
+   response = await client.execute_graphql(query=MY_QUERY)
+   data = GetDevicesQuery(**response)
+   ```