feat: refactor documentation AR-8

EXAMPLE.md

@@ -156,7 +156,7 @@ $ ariadne-codegen
 Structure of generated package:
 
 ```
-grapql_client/
+graphql_client/
     __init__.py
     async_base_client.py
     base_model.py
@@ -169,7 +169,6 @@ grapql_client/
     input_types.py
     list_all_users.py
     list_users_by_country.py
-    scalars.py
     upload_file.py
 ```
 

LICENSE

@@ -1,6 +1,6 @@
 BSD 3-Clause License
 
-Copyright (c) 2025, Mirumee Labs
+Copyright (c) 2026, Mirumee Labs
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

docs/01-introduction.md

@@ -0,0 +1,119 @@
+---
+title: Introduction
+slug: /
+---
+
+# Ariadne Code Generator
+
+[![Ariadne](https://ariadnegraphql.org/img/logo-horizontal-sm.png)](https://ariadnegraphql.org)
+
+[![Build Status](https://github.com/mirumee/ariadne-codegen/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/mirumee/ariadne-codegen/actions)
+
+Python code generator that turns a GraphQL schema and your operations into a fully typed, async (or sync) Python client built on Pydantic. You write your queries, mutations and subscriptions in GraphQL, and ariadne-codegen generates a typed Python method for each one, returning Pydantic models - so you get autocompletion and static type checking instead of hand-writing query strings and parsing raw JSON.
+
+📖 **[Documentation](./01-introduction.md)** · [Step-by-step example](./02-guides/01-step-by-step-example.md) · [Configuration reference](./03-reference/01-configuration.md)
+
+## Features
+
+- **Fully typed models** - Pydantic models for schema types, inputs, enums, fragments, and every operation's result.
+- **Typed client methods** - each query, mutation, and subscription becomes a method with typed arguments and a typed return value.
+- **[Async or sync](./02-guides/10-async-vs-sync.md)** - generate an async client (default) or a synchronous one.
+- **[Subscriptions](./02-guides/04-subscriptions.md)** - real-time updates over WebSockets (`graphql-transport-ws`).
+- **[File uploads](./02-guides/05-file-uploads.md)** - multipart requests via the GraphQL multipart request spec.
+- **[Custom scalars](./02-guides/06-custom-scalars.md)** - map GraphQL scalars to your own Python types with `serialize`/`parse` hooks.
+- **[Extensible output](./02-guides/07-extending-types.md)** - inject mixins into generated models, copy in your own files, or swap the [base client](./03-reference/02-generated-code-dependencies.md) (custom auth, or to drop the `httpx`/`websockets` deps).
+- **[Flexible schema sources](./02-guides/02-schema-sources.md)** - a local file, installed Python packages, or remote introspection.
+- **[Plugin system](./04-plugins/01-intro.md)** - customize generation through hooks, plus ready-made plugins (shorter results, extracted operation strings, forward refs, …).
+- **More** - [programmatic query building](./02-guides/12-custom-operation-builder.md), [OpenTelemetry tracing](./02-guides/09-opentelemetry.md), [multiple clients per project](./02-guides/08-multiple-clients.md), and a [schema-copy mode](./02-guides/11-schema-generation.md).
+
+## Installation
+
+```
+pip install ariadne-codegen
+```
+
+Add subscription (WebSocket) support with:
+
+```
+pip install ariadne-codegen[subscriptions]
+```
+
+## Quickstart
+
+Generate a typed client from three files.
+
+**1. Describe your schema** in `schema.graphql`:
+
+```graphql
+type Query {
+  hello(name: String!): String!
+}
+```
+
+**2. Write the operations you need** in `queries.graphql`:
+
+```graphql
+query Greet($name: String!) {
+  hello(name: $name)
+}
+```
+
+**3. Point `ariadne-codegen` at them** in `pyproject.toml`:
+
+```toml
+[tool.ariadne-codegen]
+schema_path = "schema.graphql"
+queries_path = "queries.graphql"
+```
+
+Then generate the client:
+
+```
+ariadne-codegen
+```
+
+This creates a Python package (named `graphql_client` by default) next to your
+config, with the typed client and Pydantic models generated from your schema and
+operations:
+
+```
+graphql_client/
+    __init__.py
+    async_base_client.py   # networking base client
+    base_model.py
+    client.py              # the typed Client, with a greet() method
+    enums.py
+    exceptions.py
+    greet.py               # result model for the Greet operation
+    input_types.py
+```
+
+You get one result module per operation plus shared modules for enums, input types,
+fragments and scalars. Import the client and use it right away:
+
+```python
+import asyncio
+from graphql_client import Client
+
+
+async def main():
+    async with Client(url="https://example.com/graphql") as client:
+        result = await client.greet(name="World")
+        print(result.hello)
+
+
+asyncio.run(main())
+```
+
+`greet` is a typed method generated from your `Greet` operation, and `result` is a
+validated Pydantic model. See the [step-by-step example](./02-guides/01-step-by-step-example.md)
+for a walk-through of everything that gets generated.
+
+
+## Contributing
+
+Contributions are welcome! See [Contributing](./05-community/01-contributing.md) for how to report bugs, work on issues, and open pull requests.
+
+Also make sure you follow [@AriadneGraphQL](https://twitter.com/AriadneGraphQL) on Twitter for latest updates, news and random musings!
+
+# Crafted with ❤️ by [Mirumee Labs](http://mirumee.com) <ariadne@mirumee.com>

docs/04-step-by-step-example.md → docs/02-guides/01-step-by-step-example.md

@@ -6,12 +6,15 @@ title: Step-by-step example
 
 This example shows how **ariadne-codegen** can take a GraphQL schema and a set of queries, generate a fully typed Python client, and produce ready-to-use models for queries, mutations, and subscriptions.
 
+The full source for this example (schema, queries, and generated client) is available in [EXAMPLE.md](https://github.com/mirumee/ariadne-codegen/blob/main/EXAMPLE.md).
+
 ## Schema file
 
 We start with a GraphQL schema that defines queries, mutations, and subscriptions.
 This schema includes `User` types, input objects for creating users and setting preferences, and a `Color` enum. It also shows how to use default values in input objects.
 
 ```graphql
+# /schema.graphql
 schema {
   query: Query
   mutation: Mutation
@@ -97,6 +100,7 @@ Next we define the operations we want to use: a mutation to create a user, queri
 Notice that we also define fragments (`BasicUser` and `UserPersonalData`) to reuse fields across queries.
 
 ```graphql
+# /queries.graphql
 mutation CreateUser($userData: UserCreateInput!) {
   userCreate(userData: $userData) {
     id
@@ -180,7 +184,6 @@ graphql_client/
     input_types.py
     list_all_users.py
     list_users_by_country.py
-    scalars.py
     upload_file.py
 ```
 
@@ -200,7 +203,7 @@ class Client(AsyncBaseClient):
     async def upload_file(...): ...
 ```
 
-Each method executes the corresponding GraphQL operation and returns a typed Pydantic model.
+Each method executes the corresponding GraphQL operation and returns a typed Pydantic model, except `get_users_counter`, which is a subscription method - it returns an `AsyncIterator` and yields a new model for every message. See [Subscriptions](04-subscriptions.md) for details.
 
 ### Base client
 

docs/02-guides/02-schema-sources.md

@@ -0,0 +1,104 @@
+---
+title: Schema sources
+---
+
+# Schema sources
+
+`ariadne-codegen` needs a GraphQL schema to generate a client. You can provide it
+from a local file/directory, from installed Python packages, or by introspecting a
+remote GraphQL server.
+
+Exactly one of the following settings is required - `schema_path`, `schema_paths`
+and `remote_schema_url` are **mutually exclusive**, so only one schema source may be
+used at a time:
+
+- `schema_path` - path to file/directory with GraphQL schema
+- `schema_paths` - list of local paths and/or installed-package sources to build the schema from
+- `remote_schema_url` - URL to GraphQL server, where introspection query can be performed
+
+## Local schema file
+
+Point `schema_path` at a single schema file or at a directory:
+
+```toml
+[tool.ariadne-codegen]
+schema_path = "schema.graphql"
+queries_path = "queries.graphql"
+```
+
+When `schema_path` points to a directory, `ariadne-codegen` reads every file with a
+`.graphql`, `.graphqls` or `.gql` extension in it (searched recursively) and combines
+them into a single schema.
+
+## Combining multiple schema files
+
+`schema_paths` lets you build a single schema from several sources in different
+locations - multiple files and/or directories - instead of a single `schema_path`.
+Each source is resolved and all the collected files are combined into one schema.
+
+It additionally supports importing schema files from installed Python packages, so
+codegen can resolve types that live in a shared library without copying them
+manually.
+
+Each entry in `schema_paths` is first tried as a local filesystem path, and if it
+is neither an existing file nor directory it is treated as a dotted Python import
+path. An entry must be one of the following:
+
+- a path to a directory - all `.graphql`, `.graphqls` and `.gql` files from it are included (searched recursively), eg. `./my_schemas/`
+- a path to a specific file to be used, eg. `./shared/types.graphql`
+- an absolute import path to a callable that returns a `list[str]` of file paths, eg. `some_package.get_schema_files`
+- an absolute import path to a variable holding the path to a single schema file, eg. `some_package.SCHEMA_FILE`
+- an absolute import path to a variable holding the path to a directory - all `.graphql`, `.graphqls` and `.gql` files from it are included, eg. `some_package.SCHEMA_DIR`
+
+```toml
+[tool.ariadne-codegen]
+schema_paths = [
+  "some_gql_commontypes.get_schema_files",   # callable -> returns list of paths
+  "other_pkg.SCHEMA_DIR",                     # variable -> directory
+  "./my_other_packages/",                     # local directory
+  "./foo/bar.graphql",                        # local file
+]
+queries_path = "queries.graphql"
+```
+
+## Remote schema introspection
+
+Set `remote_schema_url` to a GraphQL endpoint and `ariadne-codegen` will run an
+introspection query to retrieve the schema:
+
+```toml
+[tool.ariadne-codegen]
+remote_schema_url = "https://example.com/graphql/"
+queries_path = "queries.graphql"
+```
+
+The following options control how the introspection request is performed:
+
+- `remote_schema_headers` - extra headers that are passed along with introspection query, eg. `{"Authorization" = "Bearer token"}`. To include an environment variable in a header value, prefix the variable with `$`, eg. `{"Authorization" = "$AUTH_TOKEN"}`
+- `remote_schema_verify_ssl` (defaults to `true`) - a flag that specifies whether to verify ssl while introspecting remote schema
+- `remote_schema_timeout` (defaults to `5`) - timeout in seconds while introspecting remote schema
+- `remote_schema_http_client_path` (defaults to `None`) - dotted import path to a custom HTTP client used only for the introspection request, instead of the default `httpx` client
+
+### Introspection query options
+
+These options only apply when the schema is fetched via `remote_schema_url`. They
+map directly to the arguments of `graphql-core`'s
+[`get_introspection_query()`](https://graphql-core-3.readthedocs.io/en/latest/modules/utilities.html#graphql.utilities.get_introspection_query)
+(the config key `introspection_<name>` becomes the `<name>` argument), and they
+control which optional fields the generated introspection query asks the server
+for. They have no effect when using a local `schema_path` / `schema_paths`, because
+a local SDL already contains everything.
+
+```toml
+[tool.ariadne-codegen]
+remote_schema_url = "https://example.com/graphql/"
+queries_path = "queries.graphql"
+introspection_descriptions = true
+```
+
+- `introspection_descriptions` (defaults to `false`) – include descriptions in the introspection result
+- `introspection_input_value_deprecation` (defaults to `false`) – include deprecation information for input values
+- `introspection_specified_by_url` (defaults to `false`) – include `specifiedByUrl` for custom scalars
+- `introspection_schema_description` (defaults to `false`) – include schema description
+- `introspection_directive_is_repeatable` (defaults to `false`) – include `isRepeatable` information for directives
+- `introspection_input_object_one_of` (defaults to `false`) – include `oneOf` information for input objects