#36597: Email docs incorrectly use :meth: for functions
-------------------------------------+-------------------------------------
Reporter: Mike Edmunds | Type:
| Cleanup/optimization
Status: new | Component:
| Documentation
Version: dev | Severity: Normal
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------------+-------------------------------------
docs/topics/email.txt incorrectly uses Sphinx's [https://www.sphinx-
doc.org/en/master/usage/domains/python.html#role-py-meth :meth: role] for
cross references to several module-level functions (that are defined with
`function::` directives rather than `method::` directives). It should use
the [https://www.sphinx-doc.org/en/master/usage/domains/python.html#role-
py-func :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.]
--
Ticket URL: <https://code.djangoproject.com/ticket/36597>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To view this discussion visit
https://groups.google.com/d/msgid/django-updates/0107019916b69285-1d86bf3b-9e3b-4419-9f00-1e826d095b7a-000000%40eu-central-1.amazonses.com.
