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 Jacob Walls, 29 hours ago

Triage Stage: UnreviewedAccepted

comment:2 by Mridul, 7 hours ago

Owner: set to Mridul
Status: newassigned
Note: See TracTickets for help on using tickets.
Back to Top