move installation from README to docs (#75)

* move installation from README to docs * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
westerveltco · Oct 25, 2023 · 2931e4c · 2931e4c
1 parent d5134b1
commit 2931e4c
Show file tree

Hide file tree

Showing 5 changed files with 164 additions and 159 deletions.
diff --git a/README.md b/README.md
@@ -43,165 +43,6 @@ As `django-email-relay` is based on `django-mailer`, it shares a lot of the same
 - Emails are not sent immediately but instead saved in a database queue to be used by the relay service. This means that emails will not be sent unless the relay service is started and running.
 - Due to the distributed nature of the package and the fact that there are database models, and thus potentially migrations to apply, care should be taken when upgrading to ensure that all Django projects using `django-email-relay` are upgraded at roughly the same time. See the [Updating](#updating) section of the documentation for more information.
 
-## Requirements
-
-- Python 3.8, 3.9, 3.10, 3.11, or 3.12
-- Django 3.2, 4.1, or 4.2
-- PostgreSQL (for provided Docker image)
-
-## Installation
-
-You should install and setup the relay service provided by `django-email-relay` first before installing and configuring the Django app on your distributed Django projects. In the setup for the relay service, the database will be created and migrations will be run, which will need to be done before the distributed Django apps can use the relay service to send emails.
-
-### Relay Service
-
-The relay service provided by `django-email-relay` is responsible for reading a central database queue and sending emails from that queue through an SMTP server. As such, it should be run on infrastructure that has access to the SMTP server you would like to use. There are currently two ways to run the service:
-
-1. A Docker image
-2. A `runrelay` management command to be run from within a Django project
-
-If you are using the Docker image, only PostgreSQL is supported. However, when using the management command directly, you can use whatever database you are using with the Django project it is being run from, provided your other externally hosted Django projects that you would like to relay emails for also have access to the same database. If you would like the Docker image to support other databases, please [open an issue](https://github.com/westerveltco/django-email-relay/issues/new) and it will be considered.
-
-Installation of the relay service differs depending on whether you are using the provided Docker image or the management command.
-
-#### Docker
-
-A prebuilt Docker image is provided via the GitHub Container Registry, located here:
-
-```
-ghcr.io/westerveltco/django-email-relay
-```
-
-It can be run any way you would normally run a Docker container, for instance, through the CLI:
-
-```shell
-docker run -d \
-  -e "DATABASE_URL=postgres://email_relay_user:email_relay_password@localhost:5432/email_relay_db" \
-  -e "EMAIL_HOST=smtp.example.com" \
-  -e "EMAIL_PORT=25" \
-  --restart unless-stopped \
-  ghcr.io/westerveltco/django-email-relay:latest
-```
-
-It is recommended to pin to a specific version, though if you prefer, you can ride the lightning by always pulling the `latest` image.
-
-The `migrate` step is baked into the image, so there is no need to run it yourself.
-
-See the documentation [here](#configuration) for general information about configuring `django-email-relay`, [here](#relay-service-1) for information about configuring the relay service, and [here](#docker-1) for information specifically related to configuring the relay service as a Docker container.
-
-#### Django
-
-If you have a Django project already deployed that has access to the preferred SMTP server, you can skip using the Docker image and install the package and use the included `runrelay` management method instead.
-
-1. Install the package from PyPI:
-
-```shell
-pip install django-email-relay
-```
-
-2. Add `email_relay` to your `INSTALLED_APPS` setting:
-
-```python
-INSTALLED_APPS = [
-    # ...
-    "email_relay",
-    # ...
-]
-```
-
-3. Run the `migrate` management command to create the email relay database:
-
-```shell
-python manage.py migrate
-```
-
-4. Run the `runrelay` management command to start the relay service. This can be done in many different ways, for instance, via a task runner, such as Celery or Django-Q2, or using [supervisord](https://supervisord.org/) or systemd service unit file.
-
-```shell
-python manage.py runrelay
-```
-
-See the documentation [here](#configuration) for general information about configuring `django-email-relay`, [here](#relay-service-1) for information about configuring the relay service, and [here](#django-1) for information specifically related to configuring the relay service as a Django app.
-
-### Django App
-
-For each distributed Django project that you would like to use the preferred SMTP server, you will need to install the `django-email-relay` package and do some basic configuration.
-
-1. Install the package from PyPI:
-
-```shell
-pip install django-email-relay
-```
-
-2. Add `email_relay` to your `INSTALLED_APPS` setting:
-
-```python
-INSTALLED_APPS = [
-    # ...
-    "email_relay",
-    # ...
-]
-```
-
-3. Add the `RelayDatabaseEmailBackend` to your `EMAIL_BACKEND` setting:
-
-```python
-EMAIL_BACKEND = "email_relay.backend.RelayDatabaseEmailBackend"
-```
-
-4. Add the email relay database to your `DATABASES` setting. A default database alias is provided at `email_relay.conf.EMAIL_RELAY_DATABASE_ALIAS` which you can import and use:
-
-```python
-from email_relay.conf import EMAIL_RELAY_DATABASE_ALIAS
-
-DATABASES = {
-    # ...
-    EMAIL_RELAY_DATABASE_ALIAS: {
-        "ENGINE": "django.db.backends.postgresql",
-        "NAME": "email_relay_db",
-        "USER": "email_relay_user",
-        "PASSWORD": "email_relay_password",
-        "HOST": "localhost",
-        "PORT": "5432",
-    },
-    # ...
-}
-```
-
-If you would like to use a different database alias, you will also need to set the `DATABASE_ALIAS` setting within your `DJANGO_EMAIL_RELAY` settings:
-
-```python
-DATABASES = {
-    # ...
-    "some_alias": {
-        "ENGINE": "django.db.backends.postgresql",
-        "NAME": "email_relay_db",
-        "USER": "email_relay_user",
-        "PASSWORD": "email_relay_password",
-        "HOST": "localhost",
-        "PORT": "5432",
-    },
-    # ...
-}
-
-DJANGO_EMAIL_RELAY = {
-    # ...
-    "DATABASE_ALIAS": "some_alias",
-    # ...
-}
-```
-
-4. Add the `EmailDatabaseRouter` to your `DATABASE_ROUTERS` setting:
-
-```python
-DATABASE_ROUTERS = [
-    # ...
-    "email_relay.db.EmailDatabaseRouter",
-    # ...
-]
-```
-
-See the documentation [here](#configuration) for general information about configuring `django-email-relay`.
 
 ## License
 

diff --git a/docs/index.md b/docs/index.md
@@ -6,6 +6,7 @@
 :hidden:
 :maxdepth: 3
 
+installation/index
 usage/index
 configuration/index
 updating

diff --git a/docs/installation/django-app.md b/docs/installation/django-app.md
@@ -0,0 +1,79 @@
+# Django App
+
+For each distributed Django project that you would like to use the preferred SMTP server, you will need to install the `django-email-relay` package and do some basic configuration.
+
+1. Install the package from PyPI:
+
+```shell
+pip install django-email-relay
+```
+
+2. Add `email_relay` to your `INSTALLED_APPS` setting:
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "email_relay",
+    # ...
+]
+```
+
+3. Add the `RelayDatabaseEmailBackend` to your `EMAIL_BACKEND` setting:
+
+```python
+EMAIL_BACKEND = "email_relay.backend.RelayDatabaseEmailBackend"
+```
+
+4. Add the email relay database to your `DATABASES` setting. A default database alias is provided at `email_relay.conf.EMAIL_RELAY_DATABASE_ALIAS` which you can import and use:
+
+```python
+from email_relay.conf import EMAIL_RELAY_DATABASE_ALIAS
+
+DATABASES = {
+    # ...
+    EMAIL_RELAY_DATABASE_ALIAS: {
+        "ENGINE": "django.db.backends.postgresql",
+        "NAME": "email_relay_db",
+        "USER": "email_relay_user",
+        "PASSWORD": "email_relay_password",
+        "HOST": "localhost",
+        "PORT": "5432",
+    },
+    # ...
+}
+```
+
+If you would like to use a different database alias, you will also need to set the `DATABASE_ALIAS` setting within your `DJANGO_EMAIL_RELAY` settings:
+
+```python
+DATABASES = {
+    # ...
+    "some_alias": {
+        "ENGINE": "django.db.backends.postgresql",
+        "NAME": "email_relay_db",
+        "USER": "email_relay_user",
+        "PASSWORD": "email_relay_password",
+        "HOST": "localhost",
+        "PORT": "5432",
+    },
+    # ...
+}
+
+DJANGO_EMAIL_RELAY = {
+    # ...
+    "DATABASE_ALIAS": "some_alias",
+    # ...
+}
+```
+
+4. Add the `EmailDatabaseRouter` to your `DATABASE_ROUTERS` setting:
+
+```python
+DATABASE_ROUTERS = [
+    # ...
+    "email_relay.db.EmailDatabaseRouter",
+    # ...
+]
+```
+
+See the documentation [here](../configuration/index.md) for general information about configuring `django-email-relay`.
diff --git a/docs/installation/index.md b/docs/installation/index.md
@@ -0,0 +1,15 @@
+# Installation
+
+You should install and setup the relay service provided by `django-email-relay` first before installing and configuring the Django app on your distributed Django projects. In the setup for the relay service, the database will be created and migrations will be run, which will need to be done before the distributed Django apps can use the relay service to send emails.
+
+```{toctree}
+:hidden:
+
+relay-service
+django-app
+```
+## Requirements
+
+- Python 3.8, 3.9, 3.10, 3.11, or 3.12
+- Django 3.2, 4.1, or 4.2
+- PostgreSQL (for provided Docker image)
diff --git a/docs/installation/relay-service.md b/docs/installation/relay-service.md
@@ -0,0 +1,69 @@
+# Relay Service
+
+The relay service provided by `django-email-relay` is responsible for reading a central database queue and sending emails from that queue through an SMTP server. As such, it should be run on infrastructure that has access to the SMTP server you would like to use. There are currently two ways to run the service:
+
+1. A Docker image
+2. A `runrelay` management command to be run from within a Django project
+
+If you are using the Docker image, only PostgreSQL is supported. However, when using the management command directly, you can use whatever database you are using with the Django project it is being run from, provided your other externally hosted Django projects that you would like to relay emails for also have access to the same database. If you would like the Docker image to support other databases, please [open an issue](https://github.com/westerveltco/django-email-relay/issues/new) and it will be considered.
+
+Installation of the relay service differs depending on whether you are using the provided Docker image or the management command.
+
+## Docker
+
+A prebuilt Docker image is provided via the GitHub Container Registry, located here:
+
+```
+ghcr.io/westerveltco/django-email-relay
+```
+
+It can be run any way you would normally run a Docker container, for instance, through the CLI:
+
+```shell
+docker run -d \
+  -e "DATABASE_URL=postgres://email_relay_user:email_relay_password@localhost:5432/email_relay_db" \
+  -e "EMAIL_HOST=smtp.example.com" \
+  -e "EMAIL_PORT=25" \
+  --restart unless-stopped \
+  ghcr.io/westerveltco/django-email-relay:latest
+```
+
+It is recommended to pin to a specific version, though if you prefer, you can ride the lightning by always pulling the `latest` image.
+
+The `migrate` step is baked into the image, so there is no need to run it yourself.
+
+See the documentation [here](../configuration/index.md) for general information about configuring `django-email-relay`, [here](../configuration/relay-service.md) for information about configuring the relay service, and [here](../configuration/relay-service.md#docker) for information specifically related to configuring the relay service as a Docker container.
+
+## Django
+
+If you have a Django project already deployed that has access to the preferred SMTP server, you can skip using the Docker image and install the package and use the included `runrelay` management method instead.
+
+1. Install the package from PyPI:
+
+```shell
+pip install django-email-relay
+```
+
+2. Add `email_relay` to your `INSTALLED_APPS` setting:
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "email_relay",
+    # ...
+]
+```
+
+3. Run the `migrate` management command to create the email relay database:
+
+```shell
+python manage.py migrate
+```
+
+4. Run the `runrelay` management command to start the relay service. This can be done in many different ways, for instance, via a task runner, such as Celery or Django-Q2, or using [supervisord](https://supervisord.org/) or systemd service unit file.
+
+```shell
+python manage.py runrelay
+```
+
+See the documentation [here](../configuration/index.md) for general information about configuring `django-email-relay`, [here](../configuration/relay-service.md) for information about configuring the relay service, and [here](../configuration/relay-service.md#django) for information specifically related to configuring the relay service as a Django app.