docs: #150 start project documentation

.pre-commit-config.yaml

@@ -35,7 +35,7 @@ repos:
         language: system
         types: [python]
         args: [--config-file=pyproject.toml]
-        exclude: ^(tests/|migrations/)
+        exclude: ^(tests/|migrations/|docs/)
         require_serial: true
 
       - id: django-check

.readthedocs.yaml

@@ -0,0 +1,17 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
+
+sphinx:
+  configuration: docs/conf.py

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/requirements.txt

@@ -0,0 +1,3 @@
+sphinx>=9.1
+sphinx-rtd-theme
+django

docs/source/conf.py

@@ -0,0 +1,27 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "Django Email Learning"
+copyright = "2026, Payam Najafizadeh"
+author = "Payam Najafizadeh"
+release = "[v0.1.19]"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = []
+
+templates_path = ["_templates"]
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "alabaster"
+html_static_path = ["_static"]

docs/source/index.rst

@@ -0,0 +1,38 @@
+.. Django Email Learning documentation master file, created by
+   sphinx-quickstart on Thu Jan 22 11:34:26 2026.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Django Email Learning documentation
+===================================
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Getting Started
+
+   introduction
+   installation
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: User Guide (Platform)
+
+   platform/organizations
+   platform/courses
+   platform/learners
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Technical Reference
+
+   technical/management-commands
+
+
+.. .. toctree::
+..    :maxdepth: 1
+..    :caption: Project Philosophy
+
+..    philosophy/why-this-way
+..    philosophy/contributing

docs/source/installation.rst

@@ -0,0 +1,135 @@
+Installation
+============
+
+This guide will help you install and configure Django Email Learning in your Django project.
+
+.. warning::
+   The library is currently in its early stages of development. The current version is an alpha release,
+   and while it includes core features, it may not yet be suitable for production use and future updates may introduce breaking changes.
+
+
+Prerequisites
+-------------
+
+- Python 3.10 or higher
+- Django 5.0 or higher
+- A configured email backend (for sending course emails)
+
+Installation Steps
+------------------
+
+1. **Install the Package**
+
+   Install Django Email Learning via pip:
+
+   .. code-block:: bash
+
+       pip install django-email-learning
+
+2. **Add to INSTALLED_APPS**
+
+   Add 'django_email_learning' to your INSTALLED_APPS in settings.py:
+
+   .. code-block:: python
+
+       INSTALLED_APPS = [
+           # ... your other apps
+           'django_email_learning',
+           # ... more apps
+       ]
+
+3. **Run Database Migrations**
+
+   Create the necessary database tables:
+
+   .. code-block:: bash
+
+       python manage.py migrate django_email_learning
+
+4. **Configure URLs**
+
+   Add Django Email Learning URLs to your project's main urls.py:
+
+   .. code-block:: python
+
+       from django.urls import path, include
+
+       urlpatterns = [
+           # ... your other URL patterns
+           path('email-learning/', include('django_email_learning.urls')),
+           # ... more URL patterns
+       ]
+
+   You can change ``email-learning/`` to any URL path you prefer. This will make:
+
+   - **Platform (Admin Interface)**: Available at ``/email-learning/platform/``
+   - **Public Course Pages**: Available at ``/email-learning/public/organization/<org_id>/``
+   - **API Endpoints**: Available under ``/email-learning/api/``
+
+Access Control
+--------------
+
+**Platform Access**
+
+The course management platform (``/platform/``) requires authentication and is accessible to:
+
+- Django superusers
+- Users assigned as Organization users (managed via Django admin panel)
+
+**Public Access**
+
+Public course enrollment pages are accessible without authentication and are designed for learners to discover and enroll in courses.
+
+Configuration
+-------------
+
+Django Email Learning requires specific configuration in your Django settings. Add a ``DJANGO_EMAIL_LEARNING`` dictionary to your ``settings.py``:
+
+Required Settings
+~~~~~~~~~~~~~~~~~
+
+**SITE_BASE_URL**
+
+The base URL of your site, used to generate absolute URLs in emails and course links.
+
+.. code-block:: python
+
+    DJANGO_EMAIL_LEARNING = {
+        'SITE_BASE_URL': 'https://yourdomain.com',
+    }
+
+Optional Settings
+~~~~~~~~~~~~~~~~~
+
+**FROM_EMAIL**
+
+The default email address for outgoing course emails. If not specified, falls back to Django's ``DEFAULT_FROM_EMAIL`` setting.
+
+.. code-block:: python
+
+    DJANGO_EMAIL_LEARNING = {
+        'SITE_BASE_URL': 'https://yourdomain.com',
+        'FROM_EMAIL': 'courses@yourdomain.com',
+    }
+
+Email Backend Configuration
+---------------------------
+
+Django Email Learning sends course content and notifications via email. Ensure your Django project has a properly configured email backend:
+
+.. code-block:: python
+
+    # Example SMTP configuration
+    EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'
+    EMAIL_HOST = 'smtp.gmail.com'
+    EMAIL_PORT = 587
+    EMAIL_USE_TLS = True
+    EMAIL_HOST_USER = 'your-email@gmail.com'
+    EMAIL_HOST_PASSWORD = 'your-app-password'
+    DEFAULT_FROM_EMAIL = 'your-email@gmail.com'
+
+Management Command Scheduling
+-----------------------------
+To automate content delivery, schedule the ``deliver_contents`` management command to run at regular intervals (e.g., every 15-60 minutes) using a task scheduler like cron or Celery Beat.
+
+See `Management Commands <technical/management-commands.html>`_ for more details.

docs/source/introduction.rst

@@ -0,0 +1,69 @@
+Introduction
+============
+
+.. image::
+   https://github.com/AvaCodeSolutions/django-email-learning/raw/master/assets/Django2@2x.png
+   :alt: Django Email Learning
+   :align: center
+   :width: 200 px
+
+
+Django Email Learning is an open-source Django application by `AvaCode Solutions`_  designed to help educators,
+mentors, and developers create and manage automated learning paths.
+
+.. _AvaCode Solutions: https://avacodesolutions.com/
+
+Unlike traditional Learning Management Systems (LMS) that require students
+to log into a complex dashboard to find their content, Django Email Learning delivers
+lessons directly to the learner's inbox, ensuring high engagement where users
+already spend their time.
+
+
+Key Features
+------------
+
+* **Course Orchestration:** Easily define a sequence of lessons, quizzes, and assignments.
+* **Email-First Delivery:** Lessons are delivered via automated email triggers based on learner progress.
+* **Enrollment Pages:** Built-in public pages for learner registration.
+* **Progress Tracking:** Real-time analytics on lesson sent, quiz completions, and learner bottlenecks.
+* **Django Native:** Built as a pluggable Django app that integrates seamlessly into your existing project.
+
+.. important::
+   The library is currently in its early stages of development. The current version is an alpha release,
+   and while it includes core features, it may not yet be suitable for production use and future updates may introduce breaking changes.
+
+
+How It Works
+------------
+
+The platform follows a simple three-step lifecycle:
+
+1. **Design:** You define your Organizations, Courses, Lessons, and Quizzes in the platform section.
+2. **Enroll:** Learners join via a public-facing enrollment page. They need to provide their email to start.
+3. **Automate:** A background worker (Cron Job) monitors the schedule and sends the next piece of content to the learner's email.
+
+Who Is This For?
+----------------
+
+* **Developers:** Looking to add "drip-feed" educational content to an existing Django site.
+* **Content Creators:** Who want a lightweight, "distraction-free" way to teach their audience.
+* **Bootcamps & Organizations:** Needing a way to automate onboarding or training without forcing users to learn a new UI.
+
+The Philosophy
+--------------
+
+Most Learning Management Systems (LMS) suffer from **"Dashboard Fatigue"**—learners sign up with high intent but rarely log back in. Furthermore, traditional web-based platforms often exclude learners in regions with unstable internet connections or limited data access.
+
+**Django Email Learning** was built to solve these challenges by meeting learners where they already are: their **inbox**.
+
+
+By shifting the delivery from a heavy web interface to lightweight, automated email triggers, we provide:
+
+* **Offline Access:** Once an email is received, the lesson content is available to the learner regardless of their current connectivity.
+* **Reduced Friction:** No need to remember passwords or navigate a complex UI; the content comes to the user.
+* **Consistency:** By combining Django’s robust database logic with automated scheduling, we transform learning from a "destination" they have to visit into a passive, consistent habit.
+
+Next Steps
+----------
+
+* To get started with a new installation, head over to the :doc:`installation` guide.