id	summary	reporter	owner	description	type	status	component	version	severity	resolution	keywords	cc	stage	has_patch	needs_docs	needs_tests	needs_better_patch	easy	ui_ux
36597	Email docs incorrectly use :meth: for functions	Mike Edmunds	Mridul	"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.]"	Cleanup/optimization	closed	Documentation	dev	Normal	fixed			Ready for checkin	1	0	0	0	1	0