Merge pull request #58 from Miksus/docs/update_style

DOCS: Update style
Miksus · Oct 1, 2022 · dcd7ae6 · dcd7ae6
2 parents 2c70ae1 + 4edd37b
commit dcd7ae6
Show file tree

Hide file tree

Showing 10 changed files with 108 additions and 27 deletions.
diff --git a/README.md b/README.md
@@ -12,8 +12,9 @@
 
 
 ## What is it?
-Red Mail is an advanced email sender library. It makes sending emails trivial and 
-has a lot of advanced features such as:
+Red Mail is an advanced email sender library. 
+It is a sister library for [Red Box, advanced email reader](https://github.com/Miksus/red-box).
+It makes sending emails trivial and has a lot of advanced features such as:
 
 - [Attachments](https://red-mail.readthedocs.io/en/latest/tutorials/attachments.html)
 - [Templating (with Jinja)](https://red-mail.readthedocs.io/en/latest/tutorials/jinja_support.html)

diff --git a/docs/conf.py b/docs/conf.py
@@ -10,7 +10,6 @@
 # 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.
 #
-import sphinx_book_theme
 import os
 import sys
 sys.path.insert(0, os.path.abspath('..'))
@@ -33,7 +32,6 @@
     'sphinx.ext.autodoc', 
     'sphinx.ext.coverage', 
     'sphinx.ext.napoleon',
-    'sphinx_book_theme',
     'sphinx.ext.extlinks',
     'sphinx_copybutton',
 ]
@@ -79,7 +77,7 @@
 # a list of builtin themes.
 #
 html_title = "Red Mail"
-html_theme = 'sphinx_book_theme'
+html_theme = 'sphinx_material'
 html_favicon = 'favicon.ico'
 
 # Add any paths that contain custom static files (such as style sheets) here,
@@ -92,6 +90,43 @@
     'css/colors.css',
 ]
 
+html_sidebars = {
+    "**": [
+        "logo-text.html",
+        "globaltoc.html",
+        "localtoc.html",
+        "searchbox.html"
+    ]
+}
+
+html_theme_options = {
+    'nav_title': 'Red Box',
+
+    'color_primary': 'red',
+    'color_accent': 'grey',
+
+    'repo_url': 'https://github.com/Miksus/red-mail/',
+    'repo_name': 'Red Mail',
+    "repo_type": "github",
+
+    # Visible levels of the global TOC; -1 means unlimited
+    'globaltoc_depth': 3,
+    # If False, expand all TOC entries
+    'globaltoc_collapse': True,
+    # If True, show hidden TOC entries
+    'globaltoc_includehidden': False,
+
+    "html_minify": False,
+    "html_prettify": False,
+    "css_minify": True,
+
+    "heroes": {
+        "index": "Advanced email sending library.",
+    },
+    "nav_links": [
+    ],
+}
+
 # Cross references
 extlinks = {
     "stdlib": ("https://docs.python.org/3/library/%s", None)

diff --git a/docs/header.html b/docs/header.html
@@ -0,0 +1,28 @@
+
+ <div>
+
+    <p style="text-align: center;">
+        <img src="_static/logo.png" alt="Redbox logo">
+    </p>
+
+    <h1 style="text-align: center;"><a href="https://red-mail.readthedocs.io">Red Mail</a></h1>
+
+    <div style="text-align: center;">
+        <a href="https://github.com/Miksus/red-mail/actions/workflows/main.yml/badge.svg?branch=master" target="_blank">
+            <img src="https://github.com/Miksus/red-mail/actions/workflows/main.yml/badge.svg?branch=master" alt="Test">
+        </a>
+        <a href="https://codecov.io/gh/Miksus/red-mail" target="_blank">
+            <img src="https://codecov.io/gh/Miksus/red-mail/branch/master/graph/badge.svg?token=U2KF1QA5HT" alt="Test coverage">
+        </a>
+        <a href="https://pypi.org/project/redmail" target="_blank">
+            <img src="https://badgen.net/pypi/v/redmail?color=969696" alt="Package version">
+        </a>
+        <a href="https://pypi.org/project/redmail" target="_blank">
+            <img src="https://badgen.net/pypi/python/redmail?color=969696&labelColor=red" alt="Supported Python versions">
+        </a>
+    </div>
+    <div style="text-align: center;">
+        <iframe src="https://github.com/sponsors/Miksus/button" title="Sponsor Miksus" height="35" width="116" style="border: 0;"></iframe>
+    </div>
+</div>
+   <hr>
diff --git a/docs/index.rst b/docs/index.rst
@@ -3,14 +3,14 @@
    :description: Red Mail is an advanced email sender for Python. It is open source and well tested.
    :keywords: send, email, Python
 
-:red:`Red` Mail: Send Emails in Python
-=============================================
+.. raw:: html
+   :file: header.html
 
-.. image:: https://badgen.net/pypi/v/redmail
-   :target: https://pypi.org/project/redmail/
+- `Documentation <https://redbox.readthedocs.io/>`_
+- `Source code (Github) <https://github.com/Miksus/redbox>`_
+- `Releases (PyPI) <https://pypi.org/project/redbox/>`_
 
-.. image:: https://badgen.net/pypi/python/redmail
-   :target: https://pypi.org/project/redmail/
+This is a sister library for `Red Box, advanced email reader <https://red-box.readthedocs.io/>`_.
 
 Red Mail is a Python library for sending emails. 
 It makes sending emails very trivial regardless of whether 
@@ -27,9 +27,10 @@ Why Red Mail?
 -------------
 
 Sending emails is a pretty straight forward task.
-However, the standard SMTP libraries don't make 
-it particularly easy and sending emails **SHOULD NOT** 
-look like this:
+However, the SMTP and email libraries from the standard library 
+don't make it particularly easy. 
+
+Sending emails **SHOULD NOT** look like this:
 
 .. code-block:: python
 

diff --git a/docs/logo.png b/docs/logo.png
diff --git a/docs/tutorials/client.rst b/docs/tutorials/client.rst
@@ -29,8 +29,8 @@ which is configured as this:
     from smtplib import SMTP
 
     email = EmailSender(
-        host="smtp.myhost.com",
-        port=0,
+        host="smtp.example.com",
+        port=587,
         cls_smtp=SMTP,
         use_starttls=True
     )
@@ -46,8 +46,8 @@ You may also continue using TLS:
     from redmail import EmailSender
 
     email = EmailSender(
-        host="smtp.myhost.com",
-        port=0,
+        host="smtp.example.com",
+        port=587,
         use_starttls=False
     )
 
@@ -63,8 +63,8 @@ To use SSL:
     from smtplib import SMTP_SSL
 
     email = EmailSender(
-        host="smtp.myhost.com",
-        port=0,
+        host="smtp.example.com",
+        port=587,
         cls_smtp=SMTP_SSL,
     )
 
@@ -77,8 +77,8 @@ You may also pass the SSL context:
     from ssl import SSLContext
 
     email = EmailSender(
-        host="smtp.myhost.com",
-        port=0,
+        host="smtp.example.com",
+        port=587,
         cls_smtp=SMTP_SSL,
         context=SSLContext(...)
     )
@@ -94,8 +94,8 @@ To use LMTP:
     from smtplib import LMTP
 
     email = EmailSender(
-        host="smtp.myhost.com",
-        port=0,
+        host="smtp.example.com",
+        port=587,
         cls_smtp=LMTP
     )
 
diff --git a/docs/tutorials/getting_started.rst b/docs/tutorials/getting_started.rst
@@ -13,6 +13,12 @@ Install the package from `Pypi <https://pypi.org/project/redmail/>`_:
 
     pip install redmail
 
+Or install the package using Conda:
+
+.. code-block:: console
+
+    conda install -c conda-forge redmail
+
 .. _configure:
 
 Configuring Email

diff --git a/docs/tutorials/index.rst b/docs/tutorials/index.rst
@@ -15,7 +15,7 @@ See:
 - :ref:`This to send using HTML templates (Jinja) <templating>`
 - :ref:`This to configure Red Mail to various SMTP providers (ie. Gmail) <templating>`
 
-And see - :ref:`cookbook <cookbook>` for example use cases.
+And see :ref:`cookbook <cookbook>` for example use cases.
 
 .. toctree::
    :maxdepth: 1

diff --git a/docs/versions.rst b/docs/versions.rst
@@ -4,6 +4,15 @@
 Version history
 ===============
 
+- ``0.4.2``
+
+    - Docs: Changed docs style.
+
+- ``0.4.1``
+
+    - Add: Mypy stubs (thanks Waghabond!)
+    - Docs: Improved embedded content page.
+
 - ``0.4.0``
 
     - Rename: Changed ``user_name`` to ``username`` in ``redmail.EmailSender``. ``user_name`` still works but issues a warning.

diff --git a/requirements/docs.txt b/requirements/docs.txt
@@ -1,4 +1,5 @@
 sphinx >= 1.7.5
 pydata-sphinx-theme
-sphinx_book_theme
-sphinx-copybutton
+sphinx_material
+sphinx-copybutton
+sphinx_book_theme