Merge pull request #55 from Miksus/docs/update

DOC: Improve docs

docs/conf.py

@@ -78,7 +78,7 @@ html_theme_options = {
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_title = "Advanced Email Sender for Python"
+html_title = "Red Mail"
 html_theme = 'sphinx_book_theme'
 html_favicon = 'favicon.ico'
 

docs/extensions/flask.rst

@@ -1,3 +1,7 @@
+.. meta::
+   :description: Send email in Flask. 
+   :keywords: send, email, Python, Flask
+
 .. _ext-flask:
 
 Flask Extension

docs/extensions/logging.rst

@@ -1,3 +1,7 @@
+.. meta::
+   :description: Email logger for Python. 
+   :keywords: send, email, Python, logging
+
 .. _ext-logging:
 
 Email Logging

docs/tutorials/attachments.rst

@@ -1,4 +1,8 @@
 
+.. meta::
+   :description: Send email with attachment in Python.
+   :keywords: send, email, Python, attachment
+
 .. _attachments:
 
 Sending Email with Attachments

docs/tutorials/body_content.rst → docs/tutorials/embed/image.rst

@@ -1,20 +1,29 @@
 
-.. _embedded:
+.. meta::
+   :description: Send email with image in the body in Python. 
+   :keywords: send, email, Python, image, content
 
-Embedding Content
-=================
+.. _embedding-images:
 
-Red Mail allows to embed images and tables to the
-HTML bodies of emails. By default, tables often 
-look outdated and ugly in emails but Red Mail
-has pre-made table templates that render nicer
-looking tables from Pandas dataframes.
+Sending Email with Image in Body
+================================
 
+With Red Mail you can also embed an image directly to 
+the HTML body of an email to make them more visual.
 
-.. _embedding-images:
+Red Mail supports various types for the image:
+
+- :ref:`from path <embedding-images-path>`
+- :ref:`from raw bytes <embedding-images-bytes>`
+- :ref:`from dict <embedding-images-dict>`
+- :ref:`from Matplotlib figure <embedding-images-plt>`
+- :ref:`from Pillow image <embedding-images-pil>`
+
+
+.. _embedding-images-path:
 
-Embedded Images
----------------
+Embedding Image from path
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
 You can also embed images straight to the HTML body 
 of the email:
@@ -64,6 +73,7 @@ In addition to paths as strings, the following are supported:
 - :ref:`PIL.Image (Pillow image) <embedding-images-pil>`
 - :ref:`dict (content as bytes and specify the type) <embedding-images-dict>`
 
+
 .. _embedding-images-bytes:
 
 Embedding Image from bytes
@@ -95,7 +105,7 @@ You may also pass the image as bytes:
 
     The bytes are expected to represent a PNG image. In case your image is in 
     other format (ie. JPEG), you should specify the image using the 
-    :ref:`dict format <embedding-images-dict>`
+    :ref:`dict format <embedding-images-dict>`.
 
 .. _embedding-images-dict:
 
@@ -127,7 +137,7 @@ You may also include images using the dict format:
         }
     )
 
-This enables more control than including bytes as you may specify the ``subtype`` of the image. 
+Compared to embedding bytes, using the dict format you can also specify the ``subtype`` of the image. 
 
 .. _embedding-images-plt:
 
@@ -189,80 +199,3 @@ You may also include Pillow image:
             'my_image': img, 
         }
     )
-
-.. _embedding-tables:
-
-Embedded Tables
----------------
-
-You may include tables simply by turning them 
-to raw HTML for example using ``df.to_html()``
-in Pandas. However, this often lead to very
-ugly tables as SMTP is poor at handling CSS
-or styling in general. Here is a comparison
-of using ``df.to_html()`` directly vs embedding
-via Red Mail:
-
-|pic1| vs |pic2|
-
-.. |pic1| image:: /imgs/table_without_style.png
-   :height: 150px
-   :align: top
-   
-
-.. |pic2| image:: /imgs/table_with_style.png
-   :height: 150px
-   :align: top
-
-
-To embed tables, you can simply pass them 
-to the send function as Pandas dataframes:
-
-.. code-block:: python
-
-    # Creating a simple dataframe
-    import pandas as pd
-    df = pd.DataFrame({
-        'nums': [1,2,3],
-        'strings': ['yes', 'no', 'yes'],
-    })
-
-    # Let Red Mail to render the dataframe for you:
-    email.send(
-        subject='A prettified table',
-        receivers=['first.last@example.com'],
-        html="<h1>This is a table:</h1> {{ mytable }}",
-        body_tables={
-            'mytable': df, 
-        }
-    )
-
-
-Red Mail uses Jinja and inline HTML styling to make the
-tables look nice. Email servers typically don't handle
-well CSS.
-
-.. warning::
-
-    Red Email Pandas templating should work on various 
-    dataframe strucutres (empty, multi-indexed etc.) but
-    sometimes the rendering may be off if the dataframe
-    is especially complex in structural sense. There are
-    plans to make it even more better.
-
-You may also override the template paths (see 
-:ref:`templating`) to create custom templates
-if you wish to make your own table prettifying:
-
-.. code-block:: python
-
-    email.set_template_paths(
-        html_table="path/to/templates", 
-        text_template="path/to/templates"
-    )
-    email.default_html_theme = "my_table_template.html"
-    email.default_text_theme = "my_table_template.txt"
-
-The templates get parameter ``df`` which is the dataframe
-to be prettified.
-

docs/tutorials/embed/index.rst

@@ -0,0 +1,18 @@
+
+.. _embedded:
+
+Embedding to Body
+=================
+
+Red Mail allows to embed images and tables to the
+HTML bodies of emails. By default, tables often 
+look outdated and ugly in emails but Red Mail
+has pre-made table templates that render nicer
+looking tables from Pandas dataframes.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+   image
+   table

docs/tutorials/embed/table.rst

@@ -0,0 +1,79 @@
+.. meta::
+   :description: Send email with table in the body in Python.
+   :keywords: send, email, Python, table, content
+
+.. _embedding-tables:
+
+Sending Email with Table in Body
+================================
+
+You may include tables simply by turning them 
+to raw HTML for example using ``df.to_html()``
+in Pandas. However, this often lead to very
+ugly tables as SMTP is poor at handling CSS
+or styling in general. Here is a comparison
+of using ``df.to_html()`` directly vs embedding
+via Red Mail:
+
+|pic1| vs |pic2|
+
+.. |pic1| image:: /imgs/table_without_style.png
+   :height: 150px
+   :align: top
+   
+
+.. |pic2| image:: /imgs/table_with_style.png
+   :height: 150px
+   :align: top
+
+
+To embed tables, you can simply pass them 
+to the send function as Pandas dataframes:
+
+.. code-block:: python
+
+    # Creating a simple dataframe
+    import pandas as pd
+    df = pd.DataFrame({
+        'nums': [1,2,3],
+        'strings': ['yes', 'no', 'yes'],
+    })
+
+    # Let Red Mail to render the dataframe for you:
+    email.send(
+        subject='A prettified table',
+        receivers=['first.last@example.com'],
+        html="<h1>This is a table:</h1> {{ mytable }}",
+        body_tables={
+            'mytable': df, 
+        }
+    )
+
+
+Red Mail uses Jinja and inline HTML styling to make the
+tables look nice. Email servers typically don't handle
+well CSS.
+
+.. warning::
+
+    Red Email Pandas templating should work on various 
+    dataframe strucutres (empty, multi-indexed etc.) but
+    sometimes the rendering may be off if the dataframe
+    is especially complex in structural sense. There are
+    plans to make it even more better.
+
+You may also override the template paths (see 
+:ref:`templating`) to create custom templates
+if you wish to make your own table prettifying:
+
+.. code-block:: python
+
+    email.set_template_paths(
+        html_table="path/to/templates", 
+        text_template="path/to/templates"
+    )
+    email.default_html_theme = "my_table_template.html"
+    email.default_text_theme = "my_table_template.txt"
+
+The templates get parameter ``df`` which is the dataframe
+to be prettified.

docs/tutorials/getting_started.rst

@@ -1,3 +1,7 @@
+.. meta::
+   :description: Send email in Python. 
+   :keywords: send, email, Python
+
 .. _getting-started:
 
 Getting started
@@ -35,6 +39,10 @@ You can configure your sender by:
        port='<SMTP PORT>',
    )
 
+.. note::
+
+    The correct SMTP port is typically 587.
+
 There are guides to set up the following email providers:
 
 - :ref:`config-gmail`

docs/tutorials/index.rst

@@ -24,7 +24,7 @@ And see - :ref:`cookbook <cookbook>` for example use cases.
    getting_started
    sending
    attachments
-   body_content
+   embed/index
    jinja_support
    templating
    cookbook

docs/tutorials/jinja_support.rst

@@ -1,8 +1,11 @@
+.. meta::
+   :description: Send email in Python using Jinja. 
+   :keywords: send, email, Python, jinja
 
 .. _jinja-support:
 
-Jinja Support
-=============
+Jinja Templating
+================
 
 Red Mail uses Jinja for templating the HTML and text 
 bodies. This enables a lot of features out-of-the box.

docs/tutorials/sending.rst

@@ -1,3 +1,7 @@
+.. meta::
+   :description: Send email in Python.
+   :keywords: send, email, Python
+
 .. _sending-emails:
 
 Sending Emails

docs/tutorials/templating.rst

@@ -1,11 +1,19 @@
 
+.. meta::
+   :description: Send templated email in Python using Jinja. 
+   :keywords: send, email, Python, jinja, environment
+
 .. _templating:
 
-Using Templates
-===============
+Jinja Environments
+==================
+
+There are two ways of setting a custom Jinja env
+to Red Mail: from paths or directly setting the 
+envs.
 
-As templating relies on Jinja, you can set the 
-template path to a custom folder and 
+To set the paths and let Red Mail to create the 
+environments:
 
 .. code-block:: python
 
@@ -16,6 +24,18 @@ template path to a custom folder and
         text="path/text/templates",
     )
 
+To set the Jinja environments:
+
+.. code-block:: python
+
+    import jinja2
+
+    # Create an env
+    jinja_env = jinja2.Environment(loader=jinja2.FileSystemLoader("path/to/templates"))
+
+    email_sender.templates_html = jinja_env
+    email_sender.templates_text = jinja_env
+
 .. note::
 
     If you are dissatisfied with default HTML and text
@@ -29,6 +49,9 @@ template path to a custom folder and
             html_table="path/html/tables",
             text_table="path/text/tables",
         )
+    
+    The environments are in the attributes ``templates_html_table`` 
+    and ``templates_text_table`` respectively.
 
 Next we will make a simple template, let's call it 
 ``event_card.html``: