From c819e9741b8bd6d59a3a99d645d529ec4866225d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aur=C3=A9lien=20Amorin?= Date: Wed, 24 Jun 2026 00:56:08 +0200 Subject: [PATCH] Add Sphinx project documentation --- .gitignore | 3 +- .readthedocs.yaml | 14 +++ docs/Makefile | 20 ++++ docs/make.bat | 35 +++++++ docs/requirements.txt | 2 + docs/source/architecture.rst | 76 +++++++++++++++ docs/source/conf.py | 30 ++++++ docs/source/database.rst | 126 +++++++++++++++++++++++++ docs/source/deployment.rst | 163 +++++++++++++++++++++++++++++++++ docs/source/index.rst | 32 +++++++ docs/source/installation.rst | 173 +++++++++++++++++++++++++++++++++++ docs/source/interfaces.rst | 100 ++++++++++++++++++++ docs/source/monitoring.rst | 113 +++++++++++++++++++++++ docs/source/presentation.rst | 58 ++++++++++++ docs/source/quickstart.rst | 61 ++++++++++++ docs/source/technologies.rst | 51 +++++++++++ docs/source/usage.rst | 87 ++++++++++++++++++ 17 files changed, 1143 insertions(+), 1 deletion(-) create mode 100644 .readthedocs.yaml create mode 100644 docs/Makefile create mode 100644 docs/make.bat create mode 100644 docs/requirements.txt create mode 100644 docs/source/architecture.rst create mode 100644 docs/source/conf.py create mode 100644 docs/source/database.rst create mode 100644 docs/source/deployment.rst create mode 100644 docs/source/index.rst create mode 100644 docs/source/installation.rst create mode 100644 docs/source/interfaces.rst create mode 100644 docs/source/monitoring.rst create mode 100644 docs/source/presentation.rst create mode 100644 docs/source/quickstart.rst create mode 100644 docs/source/technologies.rst create mode 100644 docs/source/usage.rst diff --git a/.gitignore b/.gitignore index 0fb8193891..3795eeba45 100644 --- a/.gitignore +++ b/.gitignore @@ -3,4 +3,5 @@ venv .env .coverage -htmlcov/ \ No newline at end of file +htmlcov/ +docs/build/ \ No newline at end of file diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000000..247be2ccc4 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,14 @@ +version: 2 + +build: + os: ubuntu-24.04 + tools: + python: "3.7" + +sphinx: + configuration: docs/source/conf.py + fail_on_warning: true + +python: + install: + - requirements: docs/requirements.txt diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000000..d0c3cbf102 --- /dev/null +++ b/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) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000000..dc1312ab09 --- /dev/null +++ b/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 diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000000..cbe9dc2b84 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,2 @@ +Sphinx==5.3.0 +sphinx-rtd-theme==1.2.2 \ No newline at end of file diff --git a/docs/source/architecture.rst b/docs/source/architecture.rst new file mode 100644 index 0000000000..8bb84f9215 --- /dev/null +++ b/docs/source/architecture.rst @@ -0,0 +1,76 @@ +Architecture du projet +======================= + +Organisation générale +--------------------- + +Le projet suit une architecture Django modulaire. + +La configuration globale reste dans ``oc_lettings_site`` tandis que les +fonctionnalités métier sont réparties dans des applications dédiées. + +Structure principale +-------------------- + +``oc_lettings_site`` + Contient la configuration générale du projet Django, les URL principales, + la page d'accueil et les pages d'erreur personnalisées. + +``lettings`` + Gère les adresses et les locations immobilières. + +``profiles`` + Gère les profils associés aux utilisateurs Django. + +Répartition des responsabilités +------------------------------- + +Chaque application contient ses propres éléments Django : + +* modèles dans ``models.py`` ; +* vues dans ``views.py`` ; +* routes dans ``urls.py`` ; +* tests dans ``tests.py`` ou dans un dossier ``tests`` ; +* migrations dans le dossier ``migrations`` ; +* modèles HTML dans le dossier ``templates``. + +Routage des URL +--------------- + +Le fichier ``oc_lettings_site/urls.py`` centralise les routes principales et +inclut les routes propres aux applications ``lettings`` et ``profiles``. + +Chaque application possède ainsi son propre fichier ``urls.py`` afin de limiter +le couplage entre les fonctionnalités. + +Flux d'une requête +------------------ + +Lorsqu'un utilisateur accède à une page : + +#. Django analyse l'URL demandée ; +#. la route correspondante appelle une vue ; +#. la vue récupère les données nécessaires depuis les modèles ; +#. la vue transmet ces données à un template ; +#. Django génère puis retourne la réponse HTML. + +Architecture modulaire +---------------------- + +La séparation en applications permet : + +* d'isoler les responsabilités ; +* de faciliter la maintenance ; +* de limiter les dépendances entre fonctionnalités ; +* de simplifier les tests ; +* de faire évoluer une application sans modifier les autres. + +Migration depuis l'ancienne architecture +---------------------------------------- + +Les modèles autrefois regroupés dans ``oc_lettings_site`` ont été déplacés +dans les applications ``lettings`` et ``profiles``. + +Des migrations de données ont été utilisées pour copier les enregistrements +existants vers les nouvelles tables tout en conservant leurs identifiants et +leurs relations. diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000000..3722ee3088 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,30 @@ +# 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 = 'OC Lettings' +copyright = '2026, Aurélien Amorin' +author = 'Aurélien Amorin' + +version = '1.0' +release = '1.0' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [] + +templates_path = ['_templates'] +exclude_patterns = [] + +language = 'fr' + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'sphinx_rtd_theme' +html_static_path = ['_static'] diff --git a/docs/source/database.rst b/docs/source/database.rst new file mode 100644 index 0000000000..c6abfb1a69 --- /dev/null +++ b/docs/source/database.rst @@ -0,0 +1,126 @@ +Base de données et modèles +=========================== + +Base de données +--------------- + +Le projet utilise SQLite comme base de données. + +Le fichier principal est situé à la racine du projet : + +``oc-lettings-site.sqlite3`` + +Django accède aux données par l'intermédiaire de son ORM. Les requêtes SQL +directes ne sont donc pas nécessaires dans le fonctionnement normal de +l'application. + +Modèle Address +-------------- + +Le modèle ``Address`` appartient à l'application ``lettings``. + +Il représente l'adresse d'un bien immobilier et contient les informations +suivantes : + +* numéro ; +* rue ; +* ville ; +* État ou région ; +* code postal ; +* code du pays. + +La table correspondante est : + +``lettings_address`` + +Modèle Letting +-------------- + +Le modèle ``Letting`` appartient à l'application ``lettings``. + +Il représente une location et contient : + +* un titre ; +* une relation vers une adresse. + +Chaque location est associée à une seule adresse au moyen d'une relation +``OneToOneField``. + +La table correspondante est : + +``lettings_letting`` + +Modèle Profile +-------------- + +Le modèle ``Profile`` appartient à l'application ``profiles``. + +Il complète le modèle utilisateur fourni par Django et contient : + +* une relation vers un utilisateur Django ; +* une ville favorite. + +Chaque profil est associé à un seul utilisateur au moyen d'une relation +``OneToOneField``. + +La table correspondante est : + +``profiles_profile`` + +Relations principales +--------------------- + +Les principales relations de données sont les suivantes : + +* un ``Letting`` est lié à un ``Address`` ; +* un ``Profile`` est lié à un utilisateur Django ; +* la suppression d'un objet lié entraîne la suppression de l'objet dépendant + lorsque l'option ``on_delete=models.CASCADE`` est utilisée. + +Migrations +---------- + +Les migrations Django décrivent les évolutions successives de la base de +données. + +Elles sont stockées dans les dossiers suivants : + +* ``lettings/migrations`` ; +* ``profiles/migrations`` ; +* ``oc_lettings_site/migrations``. + +Lors de la séparation de l'application monolithique, des migrations de données +ont copié les anciens enregistrements vers les nouvelles tables. + +Ces migrations ont conservé : + +* les identifiants existants ; +* les relations entre les locations et les adresses ; +* les relations entre les profils et les utilisateurs. + +Commandes utiles +---------------- + +Afficher l'état des migrations : + +.. code-block:: console + + python manage.py showmigrations + +Créer une migration après une modification de modèle : + +.. code-block:: console + + python manage.py makemigrations + +Appliquer les migrations : + +.. code-block:: console + + python manage.py migrate + +Ouvrir le shell Django pour consulter les données avec l'ORM : + +.. code-block:: console + + python manage.py shell diff --git a/docs/source/deployment.rst b/docs/source/deployment.rst new file mode 100644 index 0000000000..73af62cc31 --- /dev/null +++ b/docs/source/deployment.rst @@ -0,0 +1,163 @@ +Déploiement +=========== + +Vue d'ensemble +-------------- + +Le déploiement de l'application repose sur les services suivants : + +* GitHub Actions pour exécuter la CI/CD ; +* Docker pour construire l'image de l'application ; +* Docker Hub pour stocker l'image ; +* Render pour héberger l'application. + +Le déploiement en production est déclenché uniquement depuis la branche +``master``. + +Conteneurisation +---------------- + +Le fichier ``Dockerfile`` situé à la racine du projet décrit l'image Docker de +l'application. + +L'image : + +* installe les dépendances Python ; +* copie le code du projet ; +* collecte les fichiers statiques ; +* lance l'application avec Gunicorn ; +* expose le port utilisé par le service. + +Construire l'image localement +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Depuis la racine du projet : + +.. code-block:: console + + docker build -t oc-lettings:local . + +Lancer le conteneur localement +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: console + + docker run --rm -p 8000:8000 -e SECRET_KEY=django-insecure-local -e DEBUG=False -e ALLOWED_HOSTS=localhost,127.0.0.1 oc-lettings:local + +Sous PowerShell, la commande peut être écrite sur une seule ligne : + +.. code-block:: powershell + + docker run --rm -p 8000:8000 -e SECRET_KEY=django-insecure-local -e DEBUG=False -e ALLOWED_HOSTS=localhost,127.0.0.1 oc-lettings:local + +L'application est alors accessible à l'adresse suivante : + +``http://127.0.0.1:8000/`` + +Pipeline CI/CD +-------------- + +Le workflow GitHub Actions est stocké dans le dossier : + +``.github/workflows`` + +Il comporte trois étapes principales. + +Tests +^^^^^ + +À chaque ``push`` et à chaque ``pull_request``, la CI : + +#. installe les dépendances ; +#. exécute les tests Django avec ``coverage`` ; +#. vérifie que la couverture est au moins égale à 80 % ; +#. exécute ``flake8``. + +Les commandes principales sont : + +.. code-block:: console + + coverage run manage.py test + coverage report --fail-under=80 + flake8 + +Construction et publication de l'image +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Lorsque les tests réussissent sur la branche ``master``, le workflow : + +#. construit l'image Docker ; +#. se connecte à Docker Hub ; +#. publie l'image avec le tag ``latest`` ; +#. publie également une image identifiée par le SHA du commit. + +Image de production : + +``docker.io/aurelienamorin/oc-lettings:latest`` + +Déploiement sur Render +^^^^^^^^^^^^^^^^^^^^^^ + +Après la publication de l'image Docker, GitHub Actions appelle le deploy hook +fourni par Render. + +Render récupère alors la nouvelle image ``latest`` depuis Docker Hub et +redémarre le service avec cette version. + +Variables d'environnement +------------------------- + +Les variables suivantes doivent être configurées sur Render : + +``SECRET_KEY`` + Clé secrète Django utilisée en production. + +``DEBUG`` + Doit être définie à ``False``. + +``ALLOWED_HOSTS`` + Doit contenir le nom d'hôte du service Render. + +``SENTRY_DSN`` + DSN du projet Sentry. + +``SENTRY_ENVIRONMENT`` + Environnement transmis à Sentry, par exemple ``production``. + +``PORT`` + Port fourni au conteneur par Render. + +Les secrets utilisés par GitHub Actions, notamment les identifiants Docker Hub +et l'URL du deploy hook Render, doivent être enregistrés dans les secrets du +dépôt GitHub. + +Fichiers statiques +------------------ + +WhiteNoise sert les fichiers statiques en production. + +La commande suivante collecte les fichiers statiques avant le lancement de +l'application : + +.. code-block:: console + + python manage.py collectstatic --noinput + +Application en production +------------------------- + +L'application déployée est accessible à l'adresse suivante : + +``https://oc-lettings-47nw.onrender.com/`` + +Vérifications après déploiement +------------------------------- + +Après chaque déploiement, vérifiez : + +* l'affichage de la page d'accueil ; +* la navigation vers les locations et les profils ; +* l'accès à l'interface d'administration ; +* le chargement des fichiers statiques ; +* l'absence d'erreurs dans les journaux Render ; +* la remontée des erreurs dans Sentry. diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000000..60992ea6a4 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,32 @@ +.. OC Lettings documentation master file, created by + sphinx-quickstart on Mon Jun 22 17:35:59 2026. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Documentation OC Lettings +========================= + +OC Lettings est une application Django permettant de consulter des locations +immobilières et des profils utilisateurs. + +Cette documentation présente l'installation, l'architecture, l'utilisation, +le déploiement et la maintenance de l'application. + + +.. toctree:: + :maxdepth: 2 + :caption: Sommaire: + + presentation + installation + quickstart + technologies + architecture + database + interfaces + usage + deployment + monitoring + + + diff --git a/docs/source/installation.rst b/docs/source/installation.rst new file mode 100644 index 0000000000..8a3a06fb3c --- /dev/null +++ b/docs/source/installation.rst @@ -0,0 +1,173 @@ +Installation +============ + +Prérequis +--------- + +L'installation locale nécessite les outils suivants : + +* Git ; +* Python 3.7 ; +* ``pip`` ; +* le module Python ``venv`` ; +* SQLite 3, uniquement pour consulter directement la base de données. + +Le projet doit être exécuté avec Python 3.7 afin de conserver sa compatibilité +avec Django 3.0. + +Cloner le dépôt +--------------- + +Placez-vous dans le dossier où le projet doit être installé, puis clonez le +dépôt GitHub : + +.. code-block:: console + + git clone https://github.com/Aurelien7777/Python-OC-Lettings-FR.git + cd Python-OC-Lettings-FR + +Remplacez l'URL par celle du dépôt GitHub public du projet. + +Créer l'environnement virtuel +----------------------------- + +Windows +^^^^^^^ + +Créez l'environnement virtuel avec Python 3.7 : + +.. code-block:: powershell + + py -3.7 -m venv venv + +Activez-le : + +.. code-block:: powershell + + .\venv\Scripts\Activate.ps1 + +Vérifiez la version et l'interpréteur utilisés : + +.. code-block:: powershell + + python --version + (Get-Command python).Path + +macOS et Linux +^^^^^^^^^^^^^^ + +Créez l'environnement virtuel : + +.. code-block:: console + + python3.7 -m venv venv + +Activez-le : + +.. code-block:: console + + source venv/bin/activate + +Vérifiez la version et l'interpréteur utilisés : + +.. code-block:: console + + python --version + which python + +Installer les dépendances +------------------------- + +Depuis la racine du projet : + +.. code-block:: console + + python -m pip install --upgrade pip + pip install -r requirements.txt + +Configurer les variables d'environnement +----------------------------------------- + +Créez un fichier ``.env`` à la racine du projet : + +.. code-block:: text + + SECRET_KEY=replace-with-a-local-secret-key + DEBUG=True + ALLOWED_HOSTS=localhost,127.0.0.1 + SENTRY_ENVIRONMENT=development + +Pour activer Sentry localement, ajoutez également : + +.. code-block:: text + + SENTRY_DSN=replace-with-your-sentry-dsn + +Le fichier ``.env`` contient des données sensibles et ne doit jamais être +ajouté au dépôt Git. + +Appliquer les migrations +------------------------ + +Exécutez les migrations Django : + +.. code-block:: console + + python manage.py migrate + +Cette commande crée ou met à jour les tables de la base de données selon +l'historique des migrations. + +Lancer l'application +-------------------- + +Démarrez le serveur de développement : + +.. code-block:: console + + python manage.py runserver + +L'application est ensuite accessible à l'adresse suivante : + +http://127.0.0.1:8000/ + +Créer un compte administrateur +------------------------------ + +Créez un compte administrateur local : + +.. code-block:: console + + python manage.py createsuperuser + +L'interface d'administration est disponible à l'adresse suivante : + +http://127.0.0.1:8000/admin/ + +Vérifier l'installation +----------------------- + +Vérifiez la configuration Django : + +.. code-block:: console + + python manage.py check + +Lancez les tests avec la mesure de couverture : + +.. code-block:: console + + coverage run manage.py test + +Vérifiez le linting : + +.. code-block:: console + + flake8 + +Affichez le rapport de couverture et vérifiez que le seuil minimum de 80 % est +respecté : + +.. code-block:: console + + coverage report --fail-under=80 \ No newline at end of file diff --git a/docs/source/interfaces.rst b/docs/source/interfaces.rst new file mode 100644 index 0000000000..4dae5d1c38 --- /dev/null +++ b/docs/source/interfaces.rst @@ -0,0 +1,100 @@ +Interfaces et URL +================= + +Type d'interface +---------------- + +OC Lettings ne fournit pas d'API REST. + +L'application expose des pages web générées par Django. Les données sont +récupérées par les vues, puis transmises aux templates HTML. + +Routes principales +------------------ + +Page d'accueil +^^^^^^^^^^^^^^ + +URL : + +``/`` + +Cette page permet d'accéder aux sections principales de l'application. + +Liste des locations +^^^^^^^^^^^^^^^^^^^ + +URL : + +``/lettings/`` + +Cette page affiche l'ensemble des locations disponibles. + +Détail d'une location +^^^^^^^^^^^^^^^^^^^^^ + +URL : + +``/lettings//`` + +Le paramètre ``letting_id`` correspond à l'identifiant numérique d'une +location. + +La vue récupère la location correspondante et affiche son titre ainsi que son +adresse. + +Liste des profils +^^^^^^^^^^^^^^^^^ + +URL : + +``/profiles/`` + +Cette page affiche la liste des profils utilisateurs. + +Détail d'un profil +^^^^^^^^^^^^^^^^^^ + +URL : + +``/profiles//`` + +Le paramètre ``username`` correspond au nom d'utilisateur associé au profil. + +La vue affiche les informations du profil sélectionné, notamment sa ville +favorite. + +Interface d'administration +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +URL : + +``/admin/`` + +Cette interface est fournie par Django et nécessite un compte administrateur. + +Organisation des routes +----------------------- + +Les routes principales sont déclarées dans : + +``oc_lettings_site/urls.py`` + +Les routes propres à chaque application sont déclarées dans : + +* ``lettings/urls.py`` ; +* ``profiles/urls.py``. + +Le fichier principal utilise la fonction ``include()`` afin de déléguer la +gestion des URL à chaque application. + +Gestion des erreurs +------------------- + +L'application prévoit des pages personnalisées pour les erreurs HTTP +suivantes : + +* erreur 404 : ressource introuvable ; +* erreur 500 : erreur interne du serveur. + +Les vues d'erreur sont gérées dans le projet ``oc_lettings_site``. diff --git a/docs/source/monitoring.rst b/docs/source/monitoring.rst new file mode 100644 index 0000000000..c28d478a72 --- /dev/null +++ b/docs/source/monitoring.rst @@ -0,0 +1,113 @@ +Surveillance et journalisation +============================== + +Objectif +-------- + +L'application utilise Sentry pour surveiller les erreurs rencontrées en +production et centraliser les informations utiles au diagnostic. + +Configuration de Sentry +----------------------- + +L'initialisation de Sentry est regroupée dans le module ``monitoring.py``. + +La configuration utilise principalement les variables d'environnement +suivantes : + +``SENTRY_DSN`` + Identifie le projet Sentry auquel les événements sont envoyés. + +``SENTRY_ENVIRONMENT`` + Indique l'environnement d'exécution, par exemple ``development`` ou + ``production``. + +Si ``SENTRY_DSN`` n'est pas défini, l'application peut fonctionner sans envoyer +d'événement à Sentry. + +Protection des données +---------------------- + +L'option ``send_default_pii`` est désactivée afin de ne pas transmettre +automatiquement les données personnelles des utilisateurs. + +Les mots de passe, clés secrètes, jetons et autres données sensibles ne doivent +jamais être écrits dans les journaux. + +Erreurs surveillées +------------------- + +Sentry enregistre les exceptions non gérées qui surviennent pendant +l'exécution de l'application. + +Un événement contient notamment : + +* le type de l'exception ; +* le message d'erreur ; +* la trace d'exécution ; +* l'environnement concerné ; +* la version ou le contexte disponible au moment de l'erreur. + +Journalisation +-------------- + +L'application utilise également le module ``logging`` de Python pour produire +des messages de journalisation. + +Les niveaux principaux sont : + +``DEBUG`` + Informations détaillées utiles pendant le développement. + +``INFO`` + Informations décrivant le fonctionnement normal de l'application. + +``WARNING`` + Situation inhabituelle qui ne bloque pas nécessairement l'application. + +``ERROR`` + Erreur empêchant l'exécution normale d'une opération. + +``CRITICAL`` + Erreur grave pouvant empêcher l'application de fonctionner. + +Consulter les événements +------------------------ + +Les erreurs envoyées à Sentry sont consultables depuis le tableau de bord du +projet Sentry. + +Les journaux du conteneur et du service sont également disponibles dans +l'interface Render. + +Lors de l'analyse d'un incident, vérifiez : + +#. le message d'erreur ; +#. la trace d'exécution ; +#. l'environnement concerné ; +#. l'heure de l'événement ; +#. les journaux Render associés. + +Tester la surveillance +---------------------- + +Un test de surveillance peut être effectué dans un environnement contrôlé en +provoquant volontairement une exception. + +Après le test, vérifiez que : + +* l'événement apparaît dans Sentry ; +* l'environnement indiqué est correct ; +* aucune donnée sensible n'est transmise ; +* l'application continue de fonctionner normalement après correction. + +Maintenance +----------- + +Lors d'une évolution de l'application : + +* conservez le DSN dans les variables d'environnement ; +* ne placez jamais le DSN ou la clé secrète directement dans le code ; +* utilisez des messages de logs précis et utiles ; +* évitez les messages redondants ; +* vérifiez régulièrement les événements non résolus dans Sentry. diff --git a/docs/source/presentation.rst b/docs/source/presentation.rst new file mode 100644 index 0000000000..65c0155d47 --- /dev/null +++ b/docs/source/presentation.rst @@ -0,0 +1,58 @@ +Présentation du projet +====================== + +Contexte +-------- + +OC Lettings est une application web développée avec Django pour une entreprise +spécialisée dans la location de biens immobiliers. + +L'application permet de consulter : + +* la liste des locations disponibles ; +* les informations détaillées de chaque location ; +* la liste des profils utilisateurs ; +* les informations associées à chaque profil ; +* l'interface d'administration Django. + +Objectifs du projet +------------------- + +Le projet consiste à améliorer une application Django existante sans modifier +son apparence ni ses fonctionnalités principales. + +Les objectifs techniques sont les suivants : + +* remplacer l'architecture monolithique par une architecture modulaire ; +* séparer les fonctionnalités dans les applications ``lettings`` et ``profiles`` ; +* migrer les données existantes avec les migrations Django ; +* améliorer la qualité du code avec le linting, les tests et les docstrings ; +* atteindre une couverture de tests supérieure à 80 % ; +* intégrer Sentry pour la surveillance des erreurs et des logs ; +* conteneuriser l'application avec Docker ; +* mettre en place un pipeline CI/CD avec GitHub Actions ; +* publier l'image de production sur Docker Hub ; +* déployer l'application sur Render ; +* publier la documentation technique avec Sphinx et Read the Docs. + +Architecture fonctionnelle +--------------------------- + +L'application est organisée autour de trois composants principaux : + +``oc_lettings_site`` + Contient la configuration générale du projet, la page d'accueil et les pages + d'erreur personnalisées. + +``lettings`` + Gère les adresses et les locations immobilières. + +``profiles`` + Gère les profils associés aux utilisateurs Django. + +Application en production +------------------------- + +L'application est accessible à l'adresse suivante : + +https://oc-lettings-47nw.onrender.com diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst new file mode 100644 index 0000000000..379381f48d --- /dev/null +++ b/docs/source/quickstart.rst @@ -0,0 +1,61 @@ +Démarrage rapide +================ + +Cette section suppose que l'installation et la configuration du projet ont +déjà été effectuées. + +Activer l'environnement virtuel +------------------------------- + +Sous Windows : + +.. code-block:: powershell + + .\venv\Scripts\Activate.ps1 + +Sous macOS ou Linux : + +.. code-block:: console + + source venv/bin/activate + +Préparer la base de données +--------------------------- + +Depuis la racine du projet, appliquez les migrations Django : + +.. code-block:: console + + python manage.py migrate + +Lancer le serveur +----------------- + +Démarrez le serveur de développement : + +.. code-block:: console + + python manage.py runserver + +Le serveur est alors accessible à l'adresse suivante : + +http://127.0.0.1:8000/ + +Pages principales +----------------- + +Les principales pages de l'application sont : + +* accueil : http://127.0.0.1:8000/ ; +* locations : http://127.0.0.1:8000/lettings/ ; +* profils : http://127.0.0.1:8000/profiles/ ; +* administration : http://127.0.0.1:8000/admin/. + +Arrêter le serveur +------------------ + +Dans le terminal où le serveur est lancé, utilisez la combinaison suivante : + +.. code-block:: text + + Ctrl + C diff --git a/docs/source/technologies.rst b/docs/source/technologies.rst new file mode 100644 index 0000000000..3b0dbc5bbe --- /dev/null +++ b/docs/source/technologies.rst @@ -0,0 +1,51 @@ +Technologies utilisées +======================= + +Langage et framework +-------------------- + +Le projet utilise les technologies principales suivantes : + +* Python 3.7 ; +* Django 3.0 ; +* HTML et CSS pour les modèles de pages ; +* SQLite comme base de données. + +Qualité du code et tests +------------------------ + +Les outils suivants sont utilisés pour vérifier la qualité du projet : + +* ``flake8`` pour le contrôle du style du code ; +* le test runner intégré à Django pour exécuter les tests ; +* ``coverage`` pour mesurer la couverture des tests ; +* un seuil minimal de couverture fixé à 80 % dans la CI. + +Configuration et surveillance +----------------------------- + +Le projet utilise également : + +* ``python-dotenv`` pour charger les variables d'environnement ; +* Sentry pour la surveillance des erreurs et la journalisation ; +* ``gunicorn`` comme serveur WSGI en production ; +* WhiteNoise pour servir les fichiers statiques. + +Conteneurisation et déploiement +------------------------------- + +Le déploiement repose sur : + +* Docker pour construire l'image de l'application ; +* Docker Hub pour stocker l'image ; +* GitHub Actions pour exécuter la CI/CD ; +* Render pour héberger l'application. + +Documentation +------------- + +La documentation est construite avec : + +* Sphinx ; +* le thème ``sphinx_rtd_theme`` ; +* Read the Docs pour la publication en ligne. diff --git a/docs/source/usage.rst b/docs/source/usage.rst new file mode 100644 index 0000000000..5aca9754a8 --- /dev/null +++ b/docs/source/usage.rst @@ -0,0 +1,87 @@ +Guide d'utilisation +=================== + +Accéder à l'application +----------------------- + +En local, l'application est accessible à l'adresse suivante : + +``http://127.0.0.1:8000/`` + +En production, elle est accessible à l'adresse suivante : + +``https://oc-lettings-47nw.onrender.com/`` + +Consulter les locations +----------------------- + +Depuis la page d'accueil, ouvrez la section des locations. + +La page ``/lettings/`` affiche la liste des locations disponibles. + +Sélectionnez une location pour consulter : + +* son titre ; +* son adresse complète. + +Consulter les profils +--------------------- + +Depuis la page d'accueil, ouvrez la section des profils. + +La page ``/profiles/`` affiche la liste des profils utilisateurs. + +Sélectionnez un profil pour consulter : + +* le nom de l'utilisateur ; +* sa ville favorite. + +Utiliser l'administration Django +-------------------------------- + +L'interface d'administration est disponible à l'adresse suivante : + +``/admin/`` + +Elle nécessite un compte administrateur créé avec la commande : + +.. code-block:: console + + python manage.py createsuperuser + +Après authentification, l'administrateur peut gérer les données enregistrées +dans l'application. + +Cas d'utilisation principaux +---------------------------- + +Visiteur +^^^^^^^^ + +Un visiteur peut : + +* afficher la page d'accueil ; +* consulter la liste des locations ; +* consulter le détail d'une location ; +* consulter la liste des profils ; +* consulter le détail d'un profil. + +Administrateur +^^^^^^^^^^^^^^ + +Un administrateur peut : + +* se connecter à l'interface d'administration Django ; +* ajouter, modifier ou supprimer des adresses ; +* ajouter, modifier ou supprimer des locations ; +* ajouter, modifier ou supprimer des profils ; +* gérer les utilisateurs Django. + +Arrêter l'application locale +---------------------------- + +Dans le terminal où le serveur de développement est lancé, utilisez : + +.. code-block:: text + + Ctrl + C