EmailMessage method documentation cannot be cross referenced

[Mike Edmunds]

The documentation for EmailMessage does not use standard Sphinx method:: directives for methods like message() and attach(). This makes it difficult to create references to those methods elsewhere in the documentation (e.g., in release notes). (Compare with docs for the EmailMultiAlternatives subclass, which do use method directives.)

We should update docs/topics/email.txt to use method directives for all EmailMessage methods.

(I probably wouldn't change the EmailMessage options like to and body to use attribute:: directives. I think that would create confusion about constructor params vs attributes, which are handled reasonably well by the existing approach. And I don't think it's common to link to individual options.)

[Natalia Bidart]

Sounds good, thank you Mike!

This is slightly related to #36304.

[Natalia Bidart]

(Arguably we should consider splitting the ref part of the topics/email.txt docs into its own ref file.)

[Mike Edmunds]

Replying to Natalia Bidart:

(Arguably we should consider splitting the ref part of the topics/email.txt docs into its own ref file.)

Oh my yes! And perhaps split out separate chapters for:

• using email: common settings to get email working; composing and sending messages
• extending email: developing custom EmailBackends, etc.

(But that seems like a larger discussion.)

[Natalia Bidart]

Replying to Mike Edmunds:

Replying to Natalia Bidart:

(Arguably we should consider splitting the ref part of the topics/email.txt docs into its own ref file.)

Oh my yes! And perhaps split out separate chapters for:

• using email: common settings to get email working; composing and sending messages
• extending email: developing custom EmailBackends, etc.

(But that seems like a larger discussion.)

I think that a base split of ref/non-ref would certainly be in the scope of this ticket. Then, how the remaining bits in the topics/email.txt are organized could be evaluated when the file is cleaned up. Perhaps would a couple of top-level sections suffice?

Looking forward to your ideas!

[Mike Edmunds]

I've been wanting to reorganize email.txt for a while. Based on the questions I've seen in the forums (and in the django-anymail repo), and the large number of "how to send email with Django" tutorials out there, I think the current organization is not serving users particularly well.

I'll try to put together an outline for a revision, maybe for forum discussion? And then we could figure out if there's an incremental series of changes to get there, starting with splitting out the API reference.

In the meantime, though, I'd really like to be able to use :method:django.core.mail.EmailMessage.attach etc. in the docs. I'll open a PR for that after the modern email API one lands.

[Jacob Walls <jacobtylerwalls@…>]

In 0231f71d:

Fixed #36524 -- Enabled docs cross references to EmailMessage methods.

Updated docs for class django.core.mail.EmailMessage to use Sphinx
method:: directives, allowing cross references to those methods
elsewhere in the docs.

Updated references to those methods in the email docs and 6.0 release
notes to link directly to the specific methods.