Merge branch 'feature/new-docs'

strawberry-graphql · Jun 6, 2024 · d934bfc · d934bfc
2 parents 338a2e6 + d39368d
commit d934bfc
Show file tree

Hide file tree

Showing 116 changed files with 465 additions and 181 deletions.
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -35,3 +35,4 @@ repos:
     hooks:
       - id: blacken-docs
         args: [--skip-errors]
+        files: '\.(rst|md|markdown|py|mdx)$'
diff --git a/docs/README.md → docs/README.mdx b/docs/README.md → docs/README.mdx
@@ -1,3 +1,7 @@
+---
+title: Strawberry docs
+---
+
 # Strawberry docs
 
 - [Getting started](./index.md)
@@ -38,7 +42,7 @@
 
 ## [Extensions](./extensions)
 
-## [Errors](./errors/)
+## [Errors](./errors)
 
 ## Guides
 

diff --git a/docs/_test.md → docs/_test.mdx b/docs/_test.md → docs/_test.mdx
@@ -57,20 +57,27 @@ class X:
 You can show two different code blocks next to each other (useful when comparing
 the GraphQL schema against the Python definition):
 
-```python+schema
+<CodeGrid>
+
+```python
 import strawberry
 
+
 @strawberry.type
 class Query:
     @strawberry.field
     def ping(self) -> str:
         return "pong"
----
+```
+
+```graphql
 type Query {
-    ping: String!
+  ping: String!
 }
 ```
 
+</CodeGrid>
+
 or when showing the request and response to a query:
 
 ```graphql+response

diff --git a/docs/breaking-changes.md → docs/breaking-changes.mdx b/docs/breaking-changes.md → docs/breaking-changes.mdx
diff --git a/docs/breaking-changes/0.146.0.md → docs/breaking-changes/0.146.0.mdx b/docs/breaking-changes/0.146.0.md → docs/breaking-changes/0.146.0.mdx
@@ -1,5 +1,6 @@
 ---
 title: 0.146.0 Breaking Changes
+slug: breaking-changes/0.146.0
 ---
 
 # v0.146.0 Breaking Changes - 5 December 2022

diff --git a/docs/breaking-changes/0.159.0.md → docs/breaking-changes/0.159.0.mdx b/docs/breaking-changes/0.159.0.md → docs/breaking-changes/0.159.0.mdx
@@ -1,5 +1,6 @@
 ---
 title: 0.159.0 Deprecations
+slug: breaking-changes/0.159.0
 ---
 
 # v0.159.0 Introduces changes how extension hooks are defined

diff --git a/docs/breaking-changes/0.169.0.md → docs/breaking-changes/0.169.0.mdx b/docs/breaking-changes/0.169.0.md → docs/breaking-changes/0.169.0.mdx
@@ -1,5 +1,6 @@
 ---
 title: 0.169.0 Breaking changes
+slug: breaking-changes/0.169.0
 ---
 
 # v0.169.0 Introduces a couple of breaking changes in the HTTP integrations

diff --git a/docs/breaking-changes/0.180.0.md → docs/breaking-changes/0.180.0.mdx b/docs/breaking-changes/0.180.0.md → docs/breaking-changes/0.180.0.mdx
@@ -1,5 +1,6 @@
 ---
 title: 0.180.0 Breaking changes
+slug: breaking-changes/0.180.0
 ---
 
 # v0.180.0 introduces a breaking change for the Django Channels HTTP integration

diff --git a/docs/breaking-changes/0.213.0.md → docs/breaking-changes/0.213.0.mdx b/docs/breaking-changes/0.213.0.md → docs/breaking-changes/0.213.0.mdx
@@ -1,5 +1,6 @@
 ---
 title: 0.213.0 Deprecation
+slug: breaking-changes/0.213.0
 ---
 
 # v0.213.0 introduces a deprecation for `graphiql` parameter

diff --git a/docs/breaking-changes/0.217.0.md → docs/breaking-changes/0.217.0.mdx b/docs/breaking-changes/0.217.0.md → docs/breaking-changes/0.217.0.mdx
@@ -1,5 +1,6 @@
 ---
 title: 0.217 Breaking Changes
+slug: breaking-changes/0.217.0
 ---
 
 # v0.217.0 changes how kwargs are passed to `has_permission` method

diff --git a/docs/breaking-changes/0.233.0.md → docs/breaking-changes/0.233.0.mdx b/docs/breaking-changes/0.233.0.md → docs/breaking-changes/0.233.0.mdx
@@ -1,5 +1,6 @@
 ---
 title: 0.233.0 Breaking Changes
+slug: breaking-changes/0.233.0
 ---
 
 # v0.233.0 changes the `info` argument in `resolve_reference` in Federation

diff --git a/docs/codegen/query-codegen.md → docs/codegen/query-codegen.mdx b/docs/codegen/query-codegen.md → docs/codegen/query-codegen.mdx
diff --git a/docs/codegen/schema-codegen.md → docs/codegen/schema-codegen.mdx b/docs/codegen/schema-codegen.md → docs/codegen/schema-codegen.mdx
diff --git a/docs/concepts/async.md → docs/concepts/async.mdx b/docs/concepts/async.md → docs/concepts/async.mdx
diff --git a/docs/concepts/typings.md → docs/concepts/typings.mdx b/docs/concepts/typings.md → docs/concepts/typings.mdx
diff --git a/docs/editors/mypy.md → docs/editors/mypy.mdx b/docs/editors/mypy.md → docs/editors/mypy.mdx
diff --git a/docs/editors/vscode.md → docs/editors/vscode.mdx b/docs/editors/vscode.md → docs/editors/vscode.mdx
@@ -34,4 +34,4 @@ checking mode. At the moment strict mode is not supported.
 Once you have configured the settings, you can restart VS Code and you should be
 getting type checking errors in vscode.
 
-<img src="./pylance.png" alt="Pylance showing a type error" width="1990" height="522" />
+<!-- ![Pylance showing a type error](./pylance.png) -->
diff --git a/docs/errors.md → docs/errors.mdx b/docs/errors.md → docs/errors.mdx
diff --git a/docs/errors/_template.md → docs/errors/_template.mdx b/docs/errors/_template.md → docs/errors/_template.mdx
diff --git a/docs/errors/conflicting-arguments.md → docs/errors/conflicting-arguments.mdx b/docs/errors/conflicting-arguments.md → docs/errors/conflicting-arguments.mdx
diff --git a/docs/errors/duplicated-type-name.md → docs/errors/duplicated-type-name.mdx b/docs/errors/duplicated-type-name.md → docs/errors/duplicated-type-name.mdx
diff --git a/docs/errors/invalid-argument-type.md → docs/errors/invalid-argument-type.mdx b/docs/errors/invalid-argument-type.md → docs/errors/invalid-argument-type.mdx
diff --git a/docs/errors/invalid-type-for-union-merge.md → docs/errors/invalid-type-for-union-merge.mdx b/docs/errors/invalid-type-for-union-merge.md → docs/errors/invalid-type-for-union-merge.mdx
diff --git a/docs/errors/invalid-union-type.md → docs/errors/invalid-union-type.mdx b/docs/errors/invalid-union-type.md → docs/errors/invalid-union-type.mdx
diff --git a/docs/errors/missing-arguments-annotations.md → .../errors/missing-arguments-annotations.mdx b/docs/errors/missing-arguments-annotations.md → .../errors/missing-arguments-annotations.mdx
diff --git a/docs/errors/missing-field-annotation.md → docs/errors/missing-field-annotation.mdx b/docs/errors/missing-field-annotation.md → docs/errors/missing-field-annotation.mdx
diff --git a/docs/errors/missing-return-annotation.md → docs/errors/missing-return-annotation.mdx b/docs/errors/missing-return-annotation.md → docs/errors/missing-return-annotation.mdx
diff --git a/docs/errors/node-id-annotation.md → docs/errors/node-id-annotation.mdx b/docs/errors/node-id-annotation.md → docs/errors/node-id-annotation.mdx
diff --git a/docs/errors/not-a-strawberry-enum.md → docs/errors/not-a-strawberry-enum.mdx b/docs/errors/not-a-strawberry-enum.md → docs/errors/not-a-strawberry-enum.mdx
diff --git a/docs/errors/object-is-not-an-enum.md → docs/errors/object-is-not-an-enum.mdx b/docs/errors/object-is-not-an-enum.md → docs/errors/object-is-not-an-enum.mdx
diff --git a/docs/errors/object-is-not-class.md → docs/errors/object-is-not-class.mdx b/docs/errors/object-is-not-class.md → docs/errors/object-is-not-class.mdx
diff --git a/...ission-fail-silently-requires-optional.md → ...ssion-fail-silently-requires-optional.mdx b/...ission-fail-silently-requires-optional.md → ...ssion-fail-silently-requires-optional.mdx
diff --git a/docs/errors/private-strawberry-field.md → docs/errors/private-strawberry-field.mdx b/docs/errors/private-strawberry-field.md → docs/errors/private-strawberry-field.mdx
@@ -28,11 +28,11 @@ the GraphQL schema, so using `strawberry.field` on that field won't be useful,
 since it is meant to be used to change information about a field that is exposed
 in the GraphQL schema.
 
-<!--
-    note: this makes sense, but now we don't have a way to do something like:
-    strawberry.Private[list[str]] = strawberry.field(default_factory=list)
-    (workaround is to use dataclasses.field, explained below)
--->
+<Note>
+  This makes sense, but now we don't have a way to do something like:
+  strawberry.Private[list[str]] = strawberry.field(default_factory=list)
+  (workaround is to use dataclasses.field, explained below)
+</Note>
 
 ## How to fix this error
 

diff --git a/docs/errors/relay-wrong-annotation.md → docs/errors/relay-wrong-annotation.mdx b/docs/errors/relay-wrong-annotation.md → docs/errors/relay-wrong-annotation.mdx
diff --git a/...errors/relay-wrong-resolver-annotation.md → ...rrors/relay-wrong-resolver-annotation.mdx b/...errors/relay-wrong-resolver-annotation.md → ...rrors/relay-wrong-resolver-annotation.mdx
@@ -67,10 +67,8 @@ class Query:
 ```
 
 <Note>
-
-Note that if you are returning a type different than the connection type, you
-will need to subclass the connection type and override its `resolve_node` method
-to convert it to the correct type, as explained in the
-[relay guide](../guides/relay).
-
-<Note/>
+  Note that if you are returning a type different than the connection type, you
+  will need to subclass the connection type and override its `resolve_node`
+  method to convert it to the correct type, as explained in the [relay
+  guide](../guides/relay).
+</Note>
diff --git a/docs/errors/scalar-already-registered.md → docs/errors/scalar-already-registered.mdx b/docs/errors/scalar-already-registered.md → docs/errors/scalar-already-registered.mdx
@@ -36,10 +36,10 @@ strawberry.Schema(Query)
 This happens because different types in Strawberry (and GraphQL) cannot have the
 same name.
 
-<!--
-    note: this error might happen also when trying to defined a scalar
-    with the same name as a type.
--->
+<Note>
+  This error might happen also when trying to defined a scalar with the same
+  name as a type.
+</Note>
 
 ## How to fix this error
 

diff --git a/docs/errors/unresolved-field-type.md → docs/errors/unresolved-field-type.mdx b/docs/errors/unresolved-field-type.md → docs/errors/unresolved-field-type.mdx
diff --git a/docs/errors/unsupported-type.md → docs/errors/unsupported-type.mdx b/docs/errors/unsupported-type.md → docs/errors/unsupported-type.mdx
diff --git a/docs/extensions.md → docs/extensions.mdx b/docs/extensions.md → docs/extensions.mdx
diff --git a/docs/extensions/_template.md → docs/extensions/_template.mdx b/docs/extensions/_template.md → docs/extensions/_template.mdx
diff --git a/docs/extensions/add-validation-rules.md → docs/extensions/add-validation-rules.mdx b/docs/extensions/add-validation-rules.md → docs/extensions/add-validation-rules.mdx
diff --git a/docs/extensions/apollo-tracing.md → docs/extensions/apollo-tracing.mdx b/docs/extensions/apollo-tracing.md → docs/extensions/apollo-tracing.mdx
diff --git a/docs/extensions/datadog.md → docs/extensions/datadog.mdx b/docs/extensions/datadog.md → docs/extensions/datadog.mdx
diff --git a/docs/extensions/disable-validation.md → docs/extensions/disable-validation.mdx b/docs/extensions/disable-validation.md → docs/extensions/disable-validation.mdx
diff --git a/docs/extensions/mask-errors.md → docs/extensions/mask-errors.mdx b/docs/extensions/mask-errors.md → docs/extensions/mask-errors.mdx
diff --git a/docs/extensions/max-aliases-limiter.md → docs/extensions/max-aliases-limiter.mdx b/docs/extensions/max-aliases-limiter.md → docs/extensions/max-aliases-limiter.mdx
diff --git a/docs/extensions/max-tokens-limiter.md → docs/extensions/max-tokens-limiter.mdx b/docs/extensions/max-tokens-limiter.md → docs/extensions/max-tokens-limiter.mdx
diff --git a/docs/extensions/opentelemetry.md → docs/extensions/opentelemetry.mdx b/docs/extensions/opentelemetry.md → docs/extensions/opentelemetry.mdx
diff --git a/docs/extensions/parser-cache.md → docs/extensions/parser-cache.mdx b/docs/extensions/parser-cache.md → docs/extensions/parser-cache.mdx
diff --git a/docs/extensions/pyinstrument.md → docs/extensions/pyinstrument.mdx b/docs/extensions/pyinstrument.md → docs/extensions/pyinstrument.mdx
diff --git a/docs/extensions/query-depth-limiter.md → docs/extensions/query-depth-limiter.mdx b/docs/extensions/query-depth-limiter.md → docs/extensions/query-depth-limiter.mdx
diff --git a/docs/extensions/sentry-tracing.md → docs/extensions/sentry-tracing.mdx b/docs/extensions/sentry-tracing.md → docs/extensions/sentry-tracing.mdx
diff --git a/docs/extensions/validation-cache.md → docs/extensions/validation-cache.mdx b/docs/extensions/validation-cache.md → docs/extensions/validation-cache.mdx
diff --git a/docs/faq.md → docs/faq.mdx b/docs/faq.md → docs/faq.mdx
diff --git a/docs/federation/custom_directives.md → docs/federation/custom_directives.mdx b/docs/federation/custom_directives.md → docs/federation/custom_directives.mdx
diff --git a/docs/federation/entities.md → docs/federation/entities.mdx b/docs/federation/entities.md → docs/federation/entities.mdx
diff --git a/docs/federation/entity-interfaces.md → docs/federation/entity-interfaces.mdx b/docs/federation/entity-interfaces.md → docs/federation/entity-interfaces.mdx
diff --git a/docs/federation/introduction.md → docs/federation/introduction.mdx b/docs/federation/introduction.md → docs/federation/introduction.mdx
diff --git a/docs/general/mutations.md → docs/general/mutations.mdx b/docs/general/mutations.md → docs/general/mutations.mdx
@@ -69,18 +69,23 @@ It is also possible to write a mutation that doesn't return anything.
 
 This is mapped to a `Void` GraphQL scalar, and always returns `null`
 
-```python+schema
+<CodeGrid>
+```python
 @strawberry.type
 class Mutation:
     @strawberry.mutation
     def restart() -> None:
-        print(f'Restarting the server')
----
+        print(f"Restarting the server")
+```
+
+```graphql
 type Mutation {
   restart: Void
 }
 ```
 
+</CodeGrid>
+
 <Note>
 
 Mutations with void-result go against
@@ -166,12 +171,10 @@ import strawberry
 @strawberry.type
 class FruitMutations:
     @strawberry.mutation
-    def add(self, info, input: AddFruitInput) -> Fruit:
-        # ...
+    def add(self, info, input: AddFruitInput) -> Fruit: ...
 
     @strawberry.mutation
-    def update_weight(self, info, input: UpdateFruitWeightInput) -> Fruit:
-        # ...
+    def update_weight(self, info, input: UpdateFruitWeightInput) -> Fruit: ...
 
 
 @strawberry.type
@@ -211,4 +214,5 @@ For more details, see
 [Apollo's guide on Namespaces for serial mutations](https://www.apollographql.com/docs/technotes/TN0012-namespacing-by-separation-of-concern/#namespaces-for-serial-mutations)
 and
 [Rapid API's Interactive Guide to GraphQL Queries: Aliases and Variables](https://rapidapi.com/guides/graphql-aliases-variables).
+
 </Note>
diff --git a/docs/general/queries.md → docs/general/queries.mdx b/docs/general/queries.md → docs/general/queries.mdx
diff --git a/docs/general/schema-basics.md → docs/general/schema-basics.mdx b/docs/general/schema-basics.md → docs/general/schema-basics.mdx
diff --git a/docs/general/subscriptions.md → docs/general/subscriptions.mdx b/docs/general/subscriptions.md → docs/general/subscriptions.mdx
@@ -60,7 +60,7 @@ subscription {
 
 In this example, the data looks like this as it passes over the websocket:
 
-<img src="../images/subscriptions-count-websocket.png" alt="A view of the data that's been passed via websocket" width="1013" height="267" />
+![A view of the data that's been passed via websocket](../images/subscriptions-count-websocket.png)
 
 This is a very short example of what is possible. Like with queries and
 mutations the subscription can return any GraphQL type, not only scalars as

diff --git a/docs/general/upgrades.md → docs/general/upgrades.mdx b/docs/general/upgrades.md → docs/general/upgrades.mdx
diff --git a/docs/general/why.md → docs/general/why.mdx b/docs/general/why.md → docs/general/why.mdx
@@ -27,18 +27,24 @@ GraphQL APIs while also helping finding bugs when using type checkers like MyPy.
 Here's a basic example of a type and how it compares to the equivalent type in
 GraphQL:
 
-```python+schema
+<CodeGrid>
+
+```python
 @strawberry.type
 class User:
     id: strawberry.ID
     name: str
----
+```
+
+```graphql
 type User {
   id: ID!
   name: String!
 }
 ```
 
+</CodeGrid>
+
 As you can see the code is very similar to what you would write using the
 GraphQL SDL. Thanks to this, we think Strawberry hits a perfect middle ground
 between code first and schema first.

diff --git a/docs/guides/accessing-parent-data.md → docs/guides/accessing-parent-data.mdx b/docs/guides/accessing-parent-data.md → docs/guides/accessing-parent-data.mdx
@@ -8,7 +8,9 @@ It is quite common to want to be able to access the data from the field's parent
 in a resolver. For example let's say that we want to define a `fullName` field
 on our `User`. This would be our code:
 
-```python+schema
+<CodeGrid>
+
+```python
 import strawberry
 
 
@@ -17,14 +19,18 @@ class User:
     first_name: str
     last_name: str
     full_name: str
----
+```
+
+```graphql
 type User {
-    firstName: String!
-    lastName: String!
-    fullName: String!
+  firstName: String!
+  lastName: String!
+  fullName: String!
 }
 ```
 
+</CodeGrid>
+
 In this case `full_name` will need to access the `first_name` and `last_name`
 fields, and depending on whether we define the resolver as a function or as a
 method, we'll have a few options! Let's start with the defining a resolver as a

diff --git a/docs/guides/authentication.md → docs/guides/authentication.mdx b/docs/guides/authentication.md → docs/guides/authentication.mdx
diff --git a/docs/guides/convert-to-dictionary.md → docs/guides/convert-to-dictionary.mdx b/docs/guides/convert-to-dictionary.md → docs/guides/convert-to-dictionary.mdx
diff --git a/docs/guides/custom-extensions.md → docs/guides/custom-extensions.mdx b/docs/guides/custom-extensions.md → docs/guides/custom-extensions.mdx
diff --git a/docs/guides/dataloaders.md → docs/guides/dataloaders.mdx b/docs/guides/dataloaders.md → docs/guides/dataloaders.mdx
@@ -197,15 +197,18 @@ the dataloader, in order to avoid reloading data afterwards.
 
 For example:
 
-```python+graphql
+<CodeGrid>
+
+```python
 @strawberry.type
 class Person:
     id: strawberry.ID
     friends_ids: strawberry.Private[List[strawberry.ID]]
 
     @strawberry.field
     async def friends(self) -> List[Person]:
-      return await loader.load_many(self.friends_ids)
+        return await loader.load_many(self.friends_ids)
+
 
 @strawberry.type
 class Query:
@@ -220,7 +223,9 @@ class Query:
         loader.prime_many({person.id: person for person in people})
 
         return people
----
+```
+
+```graphql
 {
   getAllPeople {
     id
@@ -231,6 +236,8 @@ class Query:
 }
 ```
 
+</CodeGrid>
+
 ### Custom Cache
 
 DataLoader's default cache is per-request and it caches data in memory. This
@@ -341,7 +348,9 @@ that allows to fetch a single user by id.
 
 We can use this query by doing the following request:
 
-```graphql+response
+<CodeGrid>
+
+```graphql
 {
   first: getUser(id: 1) {
     id
@@ -350,7 +359,9 @@ We can use this query by doing the following request:
     id
   }
 }
----
+```
+
+```json
 {
   "data": {
     "first": {
@@ -363,6 +374,8 @@ We can use this query by doing the following request:
 }
 ```
 
+</CodeGrid>
+
 Even if this query is fetching two users, it still results in one call to
 `load_users`.