Opened 29 hours ago
Last modified 7 hours ago
#36597 assigned Cleanup/optimization
Email docs incorrectly use :meth: for functions
Reported by: | Mike Edmunds | Owned by: | Mridul |
---|---|---|---|
Component: | Documentation | Version: | dev |
Severity: | Normal | Keywords: | |
Cc: | Triage Stage: | Accepted | |
Has patch: | no | Needs documentation: | no |
Needs tests: | no | Patch needs improvement: | no |
Easy pickings: | yes | UI/UX: | no |
Description
docs/topics/email.txt incorrectly uses Sphinx's :meth: role for cross references to several module-level functions (that are defined with function::
directives rather than method::
directives). It should use the :func: role.
Sphinx is pretty flexible about the whole thing, and the invalid :meth:
references still work, but it can be confusing trying to read the docs source. (What class defines the send_mail
method? Oh, none, it's actually a function.)
Example incorrect usages:
As in :meth:`~django.core.mail.send_mail`, recipients in the same… (or) As in :meth:`send_mail`, recipients in the same…
Correct usage:
Use :func:`send_mail` for straightforward email sending.…
Because send_mail
is a function, not a method:
.. function:: send_mail(subject, message, …)
Also applies to several other email functions in that same document.
[A rule of thumb is that a :meth:
reference that doesn't include a dotted ClassName.method_name
is probably incorrect, unless it appears within the class's own documentation and refers to a method of that class.]
Change History (2)
comment:1 by , 29 hours ago
Triage Stage: | Unreviewed → Accepted |
---|
comment:2 by , 7 hours ago
Owner: | set to |
---|---|
Status: | new → assigned |