Document that read_only_fields ignores explicitly declared fields

[abidaliamanat9]

Description

refs #3460

read_only_fields is implemented by merging into Meta.extra_kwargs, and explicitly declared fields skip that path. The extra_kwargs docs already mention the ignore behavior; the read_only_fields section did not.

This adds the same warning next to read_only_fields, and a one-line cross-reference under extra_kwargs.

Maintainers previously asked for this note rather than changing the API:

We could take a Note to the serialiser docs below the Additional keyword arguments section saying that both these attributes are superseded by an explicit declaration.

#3460 (comment)

I also commented on the issue:

#3460 (comment)

[Copilot]

Pull request overview

Updates the DRF serializer documentation to explicitly call out that Meta.read_only_fields does not override attributes for fields that are explicitly declared on the serializer (because the shortcut is applied via extra_kwargs, which declared fields bypass).

Changes:

• Adds an explicit warning under the read_only_fields documentation explaining the ignore behavior for explicitly declared fields.
• Adds a short cross-reference in the extra_kwargs section noting that the same rule applies to read_only_fields.

Suppressed comments (1)

docs/api-guide/serializers.md:596

• Similar to the read_only_fields note above, this sentence could be interpreted as extra_kwargs being ignored entirely rather than ignored for the explicitly declared field. Clarifying the scope (and that inherited declared fields also bypass extra_kwargs) would reduce confusion.

Please keep in mind that, if the field has already been explicitly declared on the serializer class, then the `extra_kwargs` option will be ignored. The same is true of `read_only_fields`, which is implemented using `extra_kwargs`.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.