Update docs to use myst-parser (and be written in .md) (#212)

update docs to use myst-parser (and be written in .md)

docs/changes.rst → docs/changes.md

@@ -1 +1,3 @@
+```{eval-rst}
 .. include:: ../CHANGES
+```

docs/conf.py

@@ -10,19 +10,12 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import os
-import sys
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.insert(0, os.path.abspath(".."))
-
 # -- General configuration -----------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
+    "myst_parser",
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
     "pallets_sphinx_themes",
@@ -31,9 +24,6 @@
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
-# The suffix of source filenames.
-source_suffix = ".rst"
-
 # The encoding of source files.
 # source_encoding = 'utf-8'
 

docs/index.md

@@ -0,0 +1,280 @@
+# flask-mail
+
+```{eval-rst}
+.. module:: flask-mail
+```
+
+One of the most basic functions in a web application is the ability to send
+emails to your users.
+
+The **Flask-Mail** extension provides a simple interface to set up SMTP with your
+[Flask] application and to send messages from your views and scripts.
+
+## Links
+
+- [documentation](https://flask-mail.readthedocs.io/en/latest/)
+- [source](http://github.com/pallets-eco/flask-mail)
+- {doc}`changes </changes>`
+
+## Installing Flask-Mail
+
+Install with **pip** and **easy_install**:
+
+```sh
+pip install Flask-Mail
+```
+
+or download the latest version from version control:
+
+```sh
+git clone https://github.com/mattupstate/flask-mail.git
+cd flask-mail
+python setup.py install
+```
+
+If you are using **virtualenv**, it is assumed that you are installing flask-mail
+in the same virtualenv as your Flask application(s).
+
+## Configuring Flask-Mail
+
+**Flask-Mail** is configured through the standard Flask config API. These are the available
+options (each is explained later in the documentation):
+
+- **MAIL_SERVER** : default **'localhost'**
+- **MAIL_PORT** : default **25**
+- **MAIL_USE_TLS** : default **False**
+- **MAIL_USE_SSL** : default **False**
+- **MAIL_DEBUG** : default **app.debug**
+- **MAIL_USERNAME** : default **None**
+- **MAIL_PASSWORD** : default **None**
+- **MAIL_DEFAULT_SENDER** : default **None**
+- **MAIL_MAX_EMAILS** : default **None**
+- **MAIL_SUPPRESS_SEND** : default **app.testing**
+- **MAIL_ASCII_ATTACHMENTS** : default **False**
+
+In addition the standard Flask `TESTING` configuration option is used by **Flask-Mail**
+in unit tests (see below).
+
+Emails are managed through a `Mail` instance:
+
+```py
+from flask import Flask
+from flask_mail import Mail
+
+app = Flask(__name__)
+mail = Mail(app)
+```
+
+In this case all emails are sent using the configuration values of the application that
+was passed to the `Mail` class constructor.
+
+Alternatively you can set up your `Mail` instance later at configuration time, using the
+**init_app** method:
+
+```py
+mail = Mail()
+
+app = Flask(__name__)
+mail.init_app(app)
+```
+
+In this case emails will be sent using the configuration values from Flask's `current_app`
+context global. This is useful if you have multiple applications running in the same
+process but with different configuration options.
+
+```{admonition} Load email configuration
+Note that Flask-Mail needs the configuration parameters to create a mail handler, so you have to make
+sure to load your configuration **before** the initialization of Flask-Mail (either use `Mail` class
+constructor or `init_app` method).
+```
+
+## Sending messages
+
+To send a message first create a `Message` instance:
+
+```py
+from flask_mail import Message
+
+@app.route("/")
+def index():
+
+    msg = Message("Hello",
+                  sender="[email protected]",
+                  recipients=["[email protected]"])
+```
+
+You can set the recipient emails immediately, or individually:
+
+```py
+msg.recipients = ["[email protected]"]
+msg.add_recipient("[email protected]")
+```
+
+If you have set `MAIL_DEFAULT_SENDER` you don't need to set the message
+sender explicity, as it will use this configuration value by default:
+
+```py
+msg = Message("Hello",
+              recipients=["[email protected]"])
+```
+
+If the `sender` is a two-element tuple, this will be split into name
+and address:
+
+```py
+msg = Message("Hello",
+              sender=("Me", "[email protected]"))
+
+assert msg.sender == "Me <[email protected]>"
+```
+
+The message can contain a body and/or HTML:
+
+```py
+msg.body = "testing"
+msg.html = "<b>testing</b>"
+```
+
+Finally, to send the message, you use the `Mail` instance configured with your Flask application:
+
+```py
+mail.send(msg)
+```
+
+## Bulk emails
+
+Usually in a web application you will be sending one or two emails per request. In certain situations
+you might want to be able to send perhaps dozens or hundreds of emails in a single batch - probably in
+an external process such as a command-line script or cronjob.
+
+In that case you do things slightly differently:
+
+```py
+with mail.connect() as conn:
+    for user in users:
+        message = '...'
+        subject = "hello, %s" % user.name
+        msg = Message(recipients=[user.email],
+                      body=message,
+                      subject=subject)
+
+        conn.send(msg)
+```
+
+The connection to your email host is kept alive and closed automatically once all the messages have been sent.
+
+Some mail servers set a limit on the number of emails sent in a single connection. You can set the max amount
+of emails to send before reconnecting by specifying the **MAIL_MAX_EMAILS** setting.
+
+## Attachments
+
+Adding attachments is straightforward:
+
+```py
+with app.open_resource("image.png") as fp:
+    msg.attach("image.png", "image/png", fp.read())
+```
+
+See the [API] for details.
+
+If `MAIL_ASCII_ATTACHMENTS` is set to `True`, filenames will be converted to
+an ASCII equivalent. This can be useful when using a mail relay that modify mail
+content and mess up Content-Disposition specification when filenames are UTF-8
+encoded. The conversion to ASCII is a basic removal of non-ASCII characters. It
+should be fine for any unicode character that can be decomposed by NFKD into one
+or more ASCII characters. If you need romanization/transliteration (i.e `ß` →
+`ss`) then your application should do it and pass a proper ASCII string.
+
+## Unit tests and suppressing emails
+
+When you are sending messages inside of unit tests, or in a development
+environment, it's useful to be able to suppress email sending.
+
+If the setting `TESTING` is set to `True`, emails will be
+suppressed. Calling `send()` on your messages will not result in
+any messages being actually sent.
+
+Alternatively outside a testing environment you can set `MAIL_SUPPRESS_SEND` to `True`.
+This will have the same effect.
+
+However, it's still useful to keep track of emails that would have been
+sent when you are writing unit tests.
+
+In order to keep track of dispatched emails, use the `record_messages`
+method:
+
+```py
+with mail.record_messages() as outbox:
+
+    mail.send_message(subject='testing',
+                      body='test',
+                      recipients=emails)
+
+    assert len(outbox) == 1
+    assert outbox[0].subject == "testing"
+```
+
+The **outbox** is a list of `Message` instances sent.
+
+The blinker package must be installed for this method to work.
+
+Note that the older way of doing things, appending the **outbox** to
+the `g` object, is now deprecated.
+
+## Header injection
+
+To prevent [header injection](http://www.nyphp.org/PHundamentals/8_Preventing-Email-Header-Injection) attempts to send
+a message with newlines in the subject, sender or recipient addresses will result in a `BadHeaderError`.
+
+## Signalling support
+
+```{versionadded} 0.4
+
+```
+
+**Flask-Mail** now provides signalling support through a `email_dispatched` signal. This is sent whenever an email is
+dispatched (even if the email is not actually sent, i.e. in a testing environment).
+
+A function connecting to the `email_dispatched` signal takes a `Message` instance as a first argument, and the Flask
+app instance as an optional argument:
+
+```py
+def log_message(message, app):
+    app.logger.debug(message.subject)
+
+email_dispatched.connect(log_message)
+```
+
+## API
+
+```{eval-rst}
+.. module:: flask_mail
+```
+
+```{eval-rst}
+.. autoclass:: Mail
+   :members: send, connect, send_message
+```
+
+```{eval-rst}
+.. autoclass:: Attachment
+```
+
+```{eval-rst}
+.. autoclass:: Connection
+   :members: send, send_message
+```
+
+```{eval-rst}
+.. autoclass:: Message
+   :members: attach, add_recipient
+```
+
+```{toctree}
+:maxdepth: 2
+
+changes
+```
+
+[flask]: http://flask.pocoo.org
+[github]: http://github.com/mattupstate/flask-mail