[Django] #36597: Email docs incorrectly use :meth: for functions

[Django]

#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.

[Django]

#36597: Email docs incorrectly use :meth: for functions

--------------------------------------+------------------------------------
Reporter: Mike Edmunds | Owner: (none)

Type: Cleanup/optimization | Status: new
Component: Documentation | Version: dev

Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0

--------------------------------------+------------------------------------
Changes (by Jacob Walls):

* stage: Unreviewed => Accepted

--
Ticket URL: <https://code.djangoproject.com/ticket/36597#comment:1>

[Django]

#36597: Email docs incorrectly use :meth: for functions
--------------------------------------+------------------------------------

Reporter: Mike Edmunds | Owner: Mridul
Type: Cleanup/optimization | Status: assigned

Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
--------------------------------------+------------------------------------

Changes (by Mridul):

* owner: (none) => Mridul
* status: new => assigned

--
Ticket URL: <https://code.djangoproject.com/ticket/36597#comment:2>