Switch to mkdocs material theme for documentation (#9849)

* Switch to mkdocs material theme

* Add logo

* Style badges on homepage

* Basic dark theme

* Enable a few theme features

* Customise large logo for dark theme

* CSS tweaks

* Add background grid back

* Switch to mkdocs material theme

* Add logo

* Style badges on homepage

* Basic dark theme

* Add syntax highlighting to code snippets

* Convert homepage snippets to code fences

* Update homepage logos

* Move mkdocs-material to pyproject.toml docs group

* Keep existing syntax highlighting

* Remove old docs_theme folder

* Tweak syntax highlighting colors on dark theme

* Add readthedocs config file

* Fix end of file empty lines

* Upgrade pip during install

* Remove custom styling for .prettyprint

* Remove .prettyprint border entirely

* Make tabs sticky in navbar

* Merge page ToC with navigation

* Tweak colors for more accessible contrast

* Add Figma file for the logos

* Apply suggestion from @Copilot

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Adjust styles for badges

* Enable content tabs for OS specific instructions

https://squidfunk.github.io/mkdocs-material/reference/content-tabs/

* Add icons for content tabs

* Standardize on .venv for virtualenv name in docs

* Add note about bash for Windows

---------

Co-authored-by: Asif Saif Uddin {"Auvi":"অভি"} <auvipy@gmail.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: 3 people

.gitattributes

@@ -0,0 +1 @@
+docs/theme/src/drf-logos.fig filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -1,7 +1,6 @@
 *.pyc
 *.db
 *~
-.*
 *.py.bak
 
 
@@ -14,6 +13,8 @@
 /env/
 MANIFEST
 coverage.*
+.coverage
+.cache/
 
 !.github
 !.gitignore

.readthedocs.yaml

@@ -0,0 +1,19 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version, and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+  jobs:
+    install:
+      - pip install --upgrade pip
+      - pip install -e . --group docs
+
+# Build documentation with Mkdocs
+mkdocs:
+   configuration: mkdocs.yml

docs/img/logo-dark.png

@@ -17,7 +17,7 @@
 }
 </style>
 
-<p class="badges" height=20px>
+<div class="badges">
     <iframe src="https://ghbtns.com/github-btn.html?user=encode&amp;repo=django-rest-framework&amp;type=watch&amp;count=true" class="github-star-button" allowtransparency="true" frameborder="0" scrolling="0" width="110px" height="20px"></iframe>
 
     <a href="https://github.com/encode/django-rest-framework/actions/workflows/main.yml">
@@ -27,11 +27,10 @@
     <a href="https://pypi.org/project/djangorestframework/">
         <img src="https://img.shields.io/pypi/v/djangorestframework.svg" class="status-badge">
     </a>
-</p>
+</div>
 
 ---
 
-<p>
 <h1 style="position: absolute;
     width: 1px;
     height: 1px;
@@ -41,8 +40,8 @@
     clip: rect(0,0,0,0);
     border: 0;">Django REST Framework</h1>
 
-<img alt="Django REST Framework" title="Logo by Jake 'Sid' Smith" src="img/logo.png" width="600px" style="display: block; margin: 0 auto 0 auto">
-</p>
+![Django REST Framework](img/logo-light.png#only-light)
+![Django REST Framework](img/logo-dark.png#only-dark)
 
 Django REST framework is a powerful and flexible toolkit for building Web APIs.
 
@@ -79,27 +78,35 @@ The following packages are optional:
 
 Install using `pip`, including any optional packages you want...
 
-    pip install djangorestframework
-    pip install markdown       # Markdown support for the browsable API.
-    pip install django-filter  # Filtering support
+```bash
+pip install djangorestframework
+pip install markdown       # Markdown support for the browsable API.
+pip install django-filter  # Filtering support
+```
 
 ...or clone the project from github.
 
-    git clone https://github.com/encode/django-rest-framework
+```bash
+git clone https://github.com/encode/django-rest-framework
+```
 
 Add `'rest_framework'` to your `INSTALLED_APPS` setting.
 
-    INSTALLED_APPS = [
-        ...
-        'rest_framework',
-    ]
+```python
+INSTALLED_APPS = [
+    # ...
+    "rest_framework",
+]
+```
 
 If you're intending to use the browsable API you'll probably also want to add REST framework's login and logout views.  Add the following to your root `urls.py` file.
 
-    urlpatterns = [
-        ...
-        path('api-auth/', include('rest_framework.urls'))
-    ]
+```python
+urlpatterns = [
+    # ...
+    path("api-auth/", include("rest_framework.urls"))
+]
+```
 
 Note that the URL path can be whatever you want.
 
@@ -111,44 +118,51 @@ We'll create a read-write API for accessing information on the users of our proj
 
 Any global settings for a REST framework API are kept in a single configuration dictionary named `REST_FRAMEWORK`.  Start off by adding the following to your `settings.py` module:
 
-    REST_FRAMEWORK = {
-        # Use Django's standard `django.contrib.auth` permissions,
-        # or allow read-only access for unauthenticated users.
-        'DEFAULT_PERMISSION_CLASSES': [
-            'rest_framework.permissions.DjangoModelPermissionsOrAnonReadOnly'
-        ]
-    }
+```python
+REST_FRAMEWORK = {
+    # Use Django's standard `django.contrib.auth` permissions,
+    # or allow read-only access for unauthenticated users.
+    "DEFAULT_PERMISSION_CLASSES": [
+        "rest_framework.permissions.DjangoModelPermissionsOrAnonReadOnly"
+    ]
+}
+```
 
 Don't forget to make sure you've also added `rest_framework` to your `INSTALLED_APPS`.
 
 We're ready to create our API now.
 Here's our project's root `urls.py` module:
 
-    from django.urls import path, include
-    from django.contrib.auth.models import User
-    from rest_framework import routers, serializers, viewsets
-
-    # Serializers define the API representation.
-    class UserSerializer(serializers.HyperlinkedModelSerializer):
-        class Meta:
-            model = User
-            fields = ['url', 'username', 'email', 'is_staff']
-
-    # ViewSets define the view behavior.
-    class UserViewSet(viewsets.ModelViewSet):
-        queryset = User.objects.all()
-        serializer_class = UserSerializer
-
-    # Routers provide an easy way of automatically determining the URL conf.
-    router = routers.DefaultRouter()
-    router.register(r'users', UserViewSet)
-
-    # Wire up our API using automatic URL routing.
-    # Additionally, we include login URLs for the browsable API.
-    urlpatterns = [
-        path('', include(router.urls)),
-        path('api-auth/', include('rest_framework.urls', namespace='rest_framework'))
-    ]
+```python
+from django.urls import path, include
+from django.contrib.auth.models import User
+from rest_framework import routers, serializers, viewsets
+
+
+# Serializers define the API representation.
+class UserSerializer(serializers.HyperlinkedModelSerializer):
+    class Meta:
+        model = User
+        fields = ["url", "username", "email", "is_staff"]
+
+
+# ViewSets define the view behavior.
+class UserViewSet(viewsets.ModelViewSet):
+    queryset = User.objects.all()
+    serializer_class = UserSerializer
+
+
+# Routers provide an easy way of automatically determining the URL conf.
+router = routers.DefaultRouter()
+router.register(r"users", UserViewSet)
+
+# Wire up our API using automatic URL routing.
+# Additionally, we include login URLs for the browsable API.
+urlpatterns = [
+    path("", include(router.urls)),
+    path("api-auth/", include("rest_framework.urls", namespace="rest_framework")),
+]
+```
 
 You can now open the API in your browser at [http://127.0.0.1:8000/](http://127.0.0.1:8000/), and view your new 'users' API. If you use the login control in the top right corner you'll also be able to add, create and delete users from the system.