docs: add some docs about sending app emails, and logging to email

docs/narr/email/sending.rst

@@ -0,0 +1,96 @@
+
+Sending Email
+=============
+
+Here we'll describe enough to get started sending email.
+
+
+Basics
+------
+
+To send an email you (usually) need 3 things:
+
+* key - unique key identifying the type of email
+* template - template file to render message body
+* context - context dict for template file rendering
+
+And actually the template just needs to exist somewhere it can be
+found, but when calling
+:meth:`~wuttjamaican.app.AppHandler.send_email()` you only need to
+give the key and context::
+
+   app.send_email('poser_alert_foo', {
+       'alert_type': 'foo',
+       'alert_msg': "foo has unexpected value! or something happened, etc.",
+   })
+
+In that example ``alert_type`` and ``alert_msg`` are the context, and
+the template file(s) may display either/both however it wants.
+
+If you do not provide all the needed context, you will likely get a
+template rendering error.  The only way to know for sure which context
+data is needed, is to look at the template file itself.
+
+
+Email Discovery
+---------------
+
+So how does the above work, e.g. how did it find the template?  And
+how can you know which are the "possible" email types you can send?
+
+This is covered in more detail in :doc:`custom` but for now we'll
+just say:
+
+The template folder(s) must be configured, but otherwise "any email
+type key" may be used.  As long as the template(s) is found, the email
+can be sent - albeit to global default recipients, unless that is
+further configured for the email type.
+
+In other words there is no "central registry" of the possible email
+types, per se.  In practice the list of template files, found within
+configured template folders, is effectively the list of possible email
+types.  (There is no "default template" for sending.)
+
+.. note::
+
+   At this time there are no built-in email templates for
+   WuttJamaican.  However there is (at least) one template defined in
+   `wuttaweb:email/templates
+   <https://forgejo.wuttaproject.org/wutta/wuttaweb/src/branch/master/src/wuttaweb/email/templates>`_.
+
+
+Email Delivery
+--------------
+
+If the email template can be found and rendered, it's time to "really"
+send the email.  How does that work?
+
+Various message headers may be specified by caller, but usually they
+will be auto-obtained from config.  This includes the sender and
+recipients, and subject line.  If neither specifies anything regarding
+the current email type, fallback "default" values are used (assuming
+those are configured).  This again is explained further in
+:doc:`custom`.
+
+So we have a complete message with all headers; the final step is to
+send this via SMTP.  While technically this supports sending to an
+"external" SMTP server, the suggested use case is to always send to
+localhost; to minimize lag and give full flexibility.  (If sending to
+localhost you should not need any specific config for that.)
+
+In any case here is sample config if you were to use an external
+SMTP server:
+
+.. code-block:: ini
+
+   [wutta.mail]
+   smtp.server = smtp.example.com
+   smtp.username = mailuser
+   smtp.password = mailpass
+
+.. note::
+
+   As of now, TLS is not supported!  Which is because of the preferred
+   use of localhost as SMTP server.  Obviously the local MTA software
+   (e.g. Postfix) can then send via another relay, and it should
+   probably use TLS for that.