Update docs for main website (#605)

Makefile

@@ -1,16 +1,11 @@
-.PHONY : install test serve-docs lint
+.PHONY : install test lint
 
 POETRY := $(shell command -v poetry 2> /dev/null)
-MKDOCS := $(shell command -v mkdocs 2> /dev/null)
 
-all: install test serve-docs
+all: install test
 
 install:
 	${POETRY} install
 
 test:
 	${POETRY} run pytest
-
-serve-docs:
-	poetry install
-	${MKDOCS} serve

docs/README.md

@@ -0,0 +1,38 @@
+---
+title: Strawberry Django docs
+---
+
+# Strawberry Django docs
+
+## General
+
+- [Index](./index.md)
+- [Community Projects](./community-projects.md)
+- [FAQ](./faq.md)
+
+## Guide
+
+- [Authentication](./guide/authentication.md)
+- [Export Schema](./guide/export-schema.md)
+- [Fields](./guide/fields.md)
+- [Filters](./guide/filters.md)
+- [Mutations](./guide/mutations.md)
+- [Optimizer](./guide/optimizer.md)
+- [Ordering](./guide/ordering.md)
+- [Pagination](./guide/pagination.md)
+- [Permissions](./guide/permissions.md)
+- [Queries](./guide/queries.md)
+- [Relay](./guide/relay.md)
+- [Resolvers](./guide/resolvers.md)
+- [Settings](./guide/settings.md)
+- [Subscriptions](./guide/subscriptions.md)
+- [Types](./guide/types.md)
+- [Unit Testing](./guide/unit-testing.md)
+- [Views](./guide/views.md)
+
+## Integrations
+
+- [Channels](./integrations/channels.md)
+- [Choices Field](./integrations/choices-field.md)
+- [Debug Toolbar](./integrations/debug-toolbar.md)
+- [Guardian](./integrations/guardian.md)

docs/community-projects.md

@@ -1,3 +1,7 @@
+---
+title: Community Projects
+---
+
 # Community Projects
 
 Those are some community maintained projects worth mentioning:

docs/faq.md

@@ -1,3 +1,7 @@
+---
+title: Frequently Asked Questions
+---
+
 # Frequently Asked Questions (FAQ)
 
 ## How to access Django request object in resolvers?

docs/guide/authentication.md

@@ -1,17 +1,20 @@
-# Authentication
+---
+title: Authentication
+---
 
-!!! warning
+# Authentication
 
-    This solution is enough for web browsers, but will not work for clients that
-    doesn't have a way to store cookies in it (e.g. mobile apps). For those it is
-    recommended to use token authentication methods. JWT can be used with
-    [strawberry-django-jwt](https://github.com/KundaPanda/strawberry-django-jwt)
-    lib.
+> [!WARNING]
+> This solution is enough for web browsers, but will not work for clients that
+> doesn't have a way to store cookies in it (e.g. mobile apps). For those it is
+> recommended to use token authentication methods. JWT can be used with
+> [strawberry-django-jwt](https://github.com/KundaPanda/strawberry-django-jwt)
+> lib.
 
 `strawberry_django` provides mutations to get authentication going right away.
 The `auth.register` mutation performs password validation using Django's `validate_password` method.
 
-```{.python title=types.py}
+```python title="types.py"
 import strawberry_django
 from strawberry import auto
 from django.contrib.auth import get_user_model
@@ -27,7 +30,7 @@ class UserInput:
     password: auto
 ```
 
-```{.python title=schema.py}
+```python title="schema.py"
 import strawberry
 import strawberry_django
 from .types import User, UserInput

docs/guide/export-schema.md

@@ -1,8 +1,11 @@
-# Export Schema
+---
+title: Export Schema
+---
 
-!!! info
+# Export Schema
 
-    The `export_schema` management command provided here is specifically designed for use with `strawberry_django`. The [default Strawberry export command](https://strawberry.rocks/docs/guides/schema-export) won't work with `strawberry_django` schemas because `strawberry_django` extends the base functionality of Strawberry to integrate with Django models and queries. This command ensures proper schema export functionality.
+> [!INFO]
+> The `export_schema` management command provided here is specifically designed for use with `strawberry_django`. The [default Strawberry export command](https://strawberry.rocks/docs/guides/schema-export) won't work with `strawberry_django` schemas because `strawberry_django` extends the base functionality of Strawberry to integrate with Django models and queries. This command ensures proper schema export functionality.
 
 The `export_schema` management command allows you to export a GraphQL schema defined using the `strawberry_django` library. This command converts the schema definition to GraphQL schema definition language (SDL), which can then be saved to a file or printed to the console.
 

docs/guide/fields.md

@@ -1,13 +1,16 @@
-# Defining Fields
+---
+title: Defining Fields
+---
 
-!!! tip
+# Defining Fields
 
-    It is highly recommended to enable the [Query Optimizer Extension](optimizer.md)
-    for improved performance and avoid some common pitfalls (e.g. the `n+1` issue)
+> [!TIP]
+> It is highly recommended to enable the [Query Optimizer Extension](optimizer.md)
+> for improved performance and avoid some common pitfalls (e.g. the `n+1` issue)
 
 Fields can be defined manually or `auto` type can be used for automatic type resolution. All basic field types and relation fields are supported out of the box. If you use a library that defines a custom field you will need to define an equivalent type such as `str`, `float`, `bool`, `int` or `id`.
 
-```{.python title=types.py}
+```python title="types.py"
 import strawberry_django
 from strawberry import auto
 
@@ -24,19 +27,18 @@ class Fruit2:
     name: str
 ```
 
-!!! tip
-
-    For choices using
-    [Django's TextChoices/IntegerChoices](https://docs.djangoproject.com/en/4.2/ref/models/fields/#enumeration-types)
-    it is recommented using the [django-choices-field](/integrations/choices-field) integration
-    enum handling.
+> [!TIP]
+> For choices using
+> [Django's TextChoices/IntegerChoices](https://docs.djangoproject.com/en/4.2/ref/models/fields/#enumeration-types)
+> it is recommented using the [django-choices-field](/integrations/choices-field) integration
+> enum handling.
 
 ## Relationships
 
 All one-to-one, one-to-many, many-to-one and many-to-many relationship types are supported, and the many-to-many relation is described using the `typing.List` annotation.
 The default resolver of `strawberry_django.fields()` resolves the relationship based on given type information.
 
-```{.python title=types.py}
+```python title="types.py"
 from typing import List
 
 @strawberry_django.type(models.Fruit)
@@ -63,7 +65,7 @@ situations.
 
 All Django types are encoded using the `strawberry_django.field()` field type by default. Fields can be customized with various parameters.
 
-```{.python title=types.py}
+```python title="types.py"
 @strawberry_django.type(models.Color)
 class Color:
     another_name: auto = strawberry_django.field(field_name='name')
@@ -120,9 +122,8 @@ field_type_map.update({
 
 ## Including / excluding Django model fields by name
 
-!!! warning
-
-    These new keywords should be used with caution, as they may inadvertently lead to exposure of unwanted data. Especially with `fields="__all__"` or `exclude`, sensitive model attributes may be included and made available in the schema without your awareness.
+> [!WARNING]
+> These new keywords should be used with caution, as they may inadvertently lead to exposure of unwanted data. Especially with `fields="__all__"` or `exclude`, sensitive model attributes may be included and made available in the schema without your awareness.
 
 `strawberry_django.type` includes two optional keyword fields to help you populate fields from the Django model, `fields` and `exclude`.
 
@@ -131,19 +132,19 @@ Valid values for `fields` are:
 - `__all__` to assign `strawberry.auto` as the field type for all model fields.
 - `[<List of field names>]` to assign `strawberry.auto` as the field type for the enumerated fields. These can be combined with manual type annotations if needed.
 
-```{.python title="All Fields"}
+```python title="All Fields"
 @strawberry_django.type(models.Fruit, fields="__all__")
 class FruitType:
     pass
 ```
 
-```{.python title="Enumerated Fields"}
+```python title="Enumerated Fields"
 @strawberry_django.type(models.Fruit, fields=["name", "color"])
 class FruitType:
     pass
 ```
 
-```{.python title="Overriden Fields"}
+```python title="Overriden Fields"
 @strawberry_django.type(models.Fruit, fields=["color"])
 class FruitType:
     name: str
@@ -153,13 +154,13 @@ Valid values for `exclude` are:
 
 - `[<List of field names>]` to exclude from the fields list. All other Django model fields will included and have `strawberry.auto` as the field type. These can also be overriden if another field type should be assigned. An empty list is ignored.
 
-```{.python title="Exclude Fields"}
+```python title="Exclude Fields"
 @strawberry_django.type(models.Fruit, exclude=["name"])
 class FruitType:
     pass
 ```
 
-```{.python title="Overriden Exclude Fields"}
+```python title="Overriden Exclude Fields"
 @strawberry_django.type(models.Fruit, exclude=["name"])
 class FruitType:
     color: int
@@ -172,7 +173,7 @@ Note that `fields` has precedence over `exclude`, so if both are provided, then
 If in your project, you want to change/add some of the standard `strawberry_django.field()` behaviour,
 it is possible to use your own custom field class when decorating a `strawberry_django.type` with the `field_cls` argument, e.g.
 
-```{.python title=types.py}
+```python title="types.py"
 class CustomStrawberryDjangoField(StrawberryDjangoField):
     """Your custom behaviour goes here."""