Merge branch 'encode:main' into add-docstrings-serializer-fields

.pre-commit-config.yaml

@@ -24,7 +24,7 @@ repos:
   hooks:
   - id: blacken-docs
     additional_dependencies:
-    - black==25.9.0
+    - black==26.1.0
 - repo: https://github.com/codespell-project/codespell
   # Configuration for codespell is in pyproject.toml
   rev: v2.4.1
@@ -34,11 +34,11 @@ repos:
       # python doesn't come with a toml parser prior to 3.11
       - "tomli; python_version < '3.11'"
 - repo: https://github.com/asottile/pyupgrade
-  rev: v3.21.0
+  rev: v3.21.2
   hooks:
   - id: pyupgrade
     args: ["--py310-plus", "--keep-percent-format"]
 - repo: https://github.com/tox-dev/pyproject-fmt
-  rev: v2.11.0
+  rev: v2.11.1
   hooks:
   - id: pyproject-fmt

docs/api-guide/permissions.md

@@ -138,7 +138,10 @@ Provided they inherit from `rest_framework.permissions.BasePermission`, permissi
             return Response(content)
 
 !!! note
-    Composition of permissions supports `&` (and), `|` (or) and `~` (not) operators.
+    Composition of permissions supports the `&` (and), `|` (or) and `~` (not) operators, and also allows the use of brackets `(` `)` to group expressions.
+
+    Operators follow the same precedence and associativity rules as standard logical operators (`~` highest, then `&`, then `|`).
+
 
 # API Reference
 

docs/topics/documenting-your-api.md

@@ -4,10 +4,11 @@
 >
 > — Roy Fielding, [REST APIs must be hypertext driven][cite]
 
-REST framework provides a range of different choices for documenting your API. The following
-is a non-exhaustive list of the most popular ones.
+REST framework provides a range of different choices for documenting your API. The following is a non-exhaustive list of some of the most popular options.
 
-## Third party packages for OpenAPI support
+## Third-party packages for OpenAPI support
+
+REST framework recommends using third-party packages for generating and presenting OpenAPI schemas, as they provide more features and flexibility than the built-in (deprecated) implementation.
 
 ### drf-spectacular
 
@@ -37,9 +38,9 @@ This also translates into a very useful interactive documentation viewer in the
 
 ## Built-in OpenAPI schema generation (deprecated)
 
-**Deprecation notice: REST framework's built-in support for generating OpenAPI schemas is
-deprecated in favor of 3rd party packages that can provide this functionality instead.
-As replacement, we recommend using the [drf-spectacular](#drf-spectacular) package.**
+!!! warning
+    **Deprecation notice:** REST framework's built-in support for generating OpenAPI schemas is deprecated in favor of third-party packages that provide this functionality instead. As a replacement, we recommend using **drf-spectacular**.
+
 
 There are a number of packages available that allow you to generate HTML
 documentation pages from OpenAPI schemas.