[Django] #36524: EmailMessage method documentation cannot be cross referenced

[Django]

#36524: EmailMessage method documentation cannot be cross referenced
-------------------------------------+-------------------------------------
Reporter: Mike Edmunds | Type:
| Cleanup/optimization
Status: new | Component:
| Documentation
Version: 5.2 | Severity: Normal
Keywords: email | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
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.)
--
Ticket URL: <https://code.djangoproject.com/ticket/36524>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#36524: EmailMessage method documentation cannot be cross referenced
-------------------------------------+-------------------------------------

Reporter: Mike Edmunds | Owner: (none)
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: 5.2
Severity: Normal | Resolution:

Keywords: email | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Natalia Bidart):

Sounds good, thank you Mike!

This is slightly related to #36304.
--
Ticket URL: <https://code.djangoproject.com/ticket/36524#comment:1>

[Django]

#36524: EmailMessage method documentation cannot be cross referenced
-------------------------------------+-------------------------------------
Reporter: Mike Edmunds | Owner: (none)
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: 5.2
Severity: Normal | Resolution:
Keywords: email | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Natalia Bidart):

(Arguably we should consider splitting the `ref` part of the
topics/email.txt docs into its own ref file.)
--
Ticket URL: <https://code.djangoproject.com/ticket/36524#comment:2>

[Django]

#36524: EmailMessage method documentation cannot be cross referenced

--------------------------------------+------------------------------------

Reporter: Mike Edmunds | Owner: (none)

Type: Cleanup/optimization | Status: new
Component: Core (Mail) | Version: 5.2
Severity: Normal | Resolution:
Keywords: email | Triage Stage: Accepted

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

--------------------------------------+------------------------------------
Changes (by Natalia Bidart):

* component: Documentation => Core (Mail)
* stage: Unreviewed => Accepted

--
Ticket URL: <https://code.djangoproject.com/ticket/36524#comment:3>

[Django]

#36524: EmailMessage method documentation cannot be cross referenced
--------------------------------------+------------------------------------
Reporter: Mike Edmunds | Owner: (none)
Type: Cleanup/optimization | Status: new
Component: Core (Mail) | Version: 5.2
Severity: Normal | Resolution:
Keywords: email | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
--------------------------------------+------------------------------------

Comment (by Mike Edmunds):

Replying to [comment:2 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.)
--
Ticket URL: <https://code.djangoproject.com/ticket/36524#comment:4>

[Django]

#36524: EmailMessage method documentation cannot be cross referenced

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

Component: Core (Mail) | Version: 5.2
Severity: Normal | Resolution:
Keywords: email | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0

-------------------------------------+-------------------------------------
Changes (by Mike Edmunds):

* owner: (none) => Mike Edmunds
* status: new => assigned

--
Ticket URL: <https://code.djangoproject.com/ticket/36524#comment:5>

[Django]

#36524: EmailMessage method documentation cannot be cross referenced
-------------------------------------+-------------------------------------
Reporter: Mike Edmunds | Owner: Mike
Type: | Edmunds
Cleanup/optimization | Status: assigned
Component: Core (Mail) | Version: 5.2
Severity: Normal | Resolution:
Keywords: email | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Natalia Bidart):

Replying to [comment:4 Mike Edmunds]:

> Replying to [comment:2 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!
--
Ticket URL: <https://code.djangoproject.com/ticket/36524#comment:6>

[Django]

#36524: EmailMessage method documentation cannot be cross referenced
-------------------------------------+-------------------------------------
Reporter: Mike Edmunds | Owner: Mike
Type: | Edmunds
Cleanup/optimization | Status: assigned
Component: Core (Mail) | Version: 5.2
Severity: Normal | Resolution:
Keywords: email | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by 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.
--
Ticket URL: <https://code.djangoproject.com/ticket/36524#comment:7>

[Django]

#36524: EmailMessage method documentation cannot be cross referenced
-------------------------------------+-------------------------------------
Reporter: Mike Edmunds | Owner: Mike
Type: | Edmunds
Cleanup/optimization | Status: assigned
Component: Core (Mail) | Version: 5.2
Severity: Normal | Resolution:
Keywords: email | Triage Stage: Accepted

Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Mike Edmunds):

* has_patch: 0 => 1

--
Ticket URL: <https://code.djangoproject.com/ticket/36524#comment:8>

[Django]

#36524: EmailMessage method documentation cannot be cross referenced
-------------------------------------+-------------------------------------
Reporter: Mike Edmunds | Owner: Mike
Type: | Edmunds
Cleanup/optimization | Status: assigned
Component: Core (Mail) | Version: 5.2
Severity: Normal | Resolution:

Keywords: email | Triage Stage: Ready for
| checkin

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

Changes (by Clifford Gama):

* stage: Accepted => Ready for checkin

--
Ticket URL: <https://code.djangoproject.com/ticket/36524#comment:9>

[Django]

#36524: EmailMessage method documentation cannot be cross referenced
-------------------------------------+-------------------------------------
Reporter: Mike Edmunds | Owner: Mike
Type: | Edmunds

Cleanup/optimization | Status: closed

Component: Core (Mail) | Version: 5.2

Severity: Normal | Resolution: fixed

Keywords: email | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Jacob Walls <jacobtylerwalls@…>):

* resolution: => fixed
* status: assigned => closed

Comment:

In [changeset:"0231f71d31b3afa92b9b5b64ddad7efb9fab9a40" 0231f71d]:
{{{#!CommitTicketReference repository=""
revision="0231f71d31b3afa92b9b5b64ddad7efb9fab9a40"
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.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/36524#comment:10>