diff --git a/docs/source/1_user/2_concepts/3_researchgroups/index.rst b/docs/source/1_user/2_concepts/3_researchgroups/index.rst index 4d94db2..79958d8 100644 --- a/docs/source/1_user/2_concepts/3_researchgroups/index.rst +++ b/docs/source/1_user/2_concepts/3_researchgroups/index.rst @@ -64,6 +64,6 @@ Il creatore di un gruppo è l'unico utente in grado di **cancellare** il gruppo Gruppi nell'interfaccia web --------------------------- -Dopo aver effettuato l'accesso come :ref:`utente` o :ref:`ospite`, l'interfaccia utente di Sophon visualizza l'elenco di gruppi di ricerca disponibili nell':ref:`instanza`, permettendo agli utenti di unirsi ad essi, lasciarli, oppure eliminarli. +Dopo aver effettuato l'accesso come :ref:`utente` o :ref:`ospite`, l'interfaccia utente di Sophon visualizza l'elenco di gruppi di ricerca disponibili nell':ref:`istanza`, permettendo agli utenti di unirsi ad essi, lasciarli, oppure eliminarli. .. image:: list.png diff --git a/docs/source/2_admin/1_installation/4_configuring_compose.rst b/docs/source/2_admin/1_installation/4_configuring_compose.rst index fc052dc..7a964c1 100644 --- a/docs/source/2_admin/1_installation/4_configuring_compose.rst +++ b/docs/source/2_admin/1_installation/4_configuring_compose.rst @@ -15,7 +15,7 @@ In particolare, tutte le impostazioni precedute da ``# INSTALL`` vanno obbligato Specifica la chiave segreta da usare per i cookie di sessione. -.. code-block:: yml +.. code-block:: yaml - DJANGO_SECRET_KEY=do-not-use-this-key-in-production-or-you-will-get-hacked @@ -41,7 +41,7 @@ Specifica la chiave segreta da usare per i cookie di sessione. Specifica il dominio che dovrà essere usato come radice per il proxy, ovvero il dominio per il quale si è configurato il DNS in precedenza. -.. code-block:: yml +.. code-block:: yaml - DJANGO_PROXY_BASE_DOMAIN=ilmiosophon.it @@ -61,7 +61,7 @@ Specifica il protocollo che dovrà essere usato nei mapping del proxy. Si consiglia vivamente di utilizzare ``https``, ma è un valore valido anche ``http``. -.. code-block:: yml +.. code-block:: yaml - DJANGO_PROXY_PROTOCOL=https @@ -75,7 +75,7 @@ Per specificare più domini, è necessario separarli con dei pipe ``|`` . Eccetto in configurazioni speciali, deve essere uguale al dominio prefisso da ``api.``. -.. code-block:: yml +.. code-block:: yaml - DJANGO_ALLOWED_HOSTS=api.ilmiosophon.it @@ -93,7 +93,7 @@ Per specificare più domini, è necessario separarli con dei pipe ``|`` . Eccetto in configurazioni speciali, deve contenere il proprio dominio prefisso dal protocollo, e in aggiunta il dominio speciale ``https://sophon.steffo.eu``, necessario per permettere l'accesso dall'interfaccia web "universale" di Sophon. -.. code-block:: yml +.. code-block:: yaml - DJANGO_ALLOWED_ORIGINS=https://ilmiosophon.it|https://sophon.steffo.eu @@ -109,7 +109,7 @@ Specifica l'URL a cui saranno accessibili i file statici di Sophon. Eccetto in configurazioni speciali, deve essere uguale alla seguente stringa, con le parole in maiuscolo sostituite rispettivamente dal protocollo e dal dominio selezionato: ``PROTOCOLLO://static.DOMINIO/django-static/``. -.. code-block:: yml +.. code-block:: yaml - DJANGO_ALLOWED_ORIGINS=http://static.ilmiosophon.it/django-static/ @@ -129,7 +129,7 @@ Specifica la lingua che deve usare Sophon nei messaggi di errore. Usa il formato `language code`_ di Django. -.. code-block:: yml +.. code-block:: yaml - DJANGO_LANGUAGE_CODE=en-us @@ -147,7 +147,7 @@ Specifica il fuso orario che deve usare Sophon nell'interfaccia di amministrazio Usa il formato `tzdata`_. -.. code-block:: yml +.. code-block:: yaml - DJANGO_TIME_ZONE=Europe/Paris @@ -163,7 +163,7 @@ Usa il formato `tzdata`_. Specifica il nome del :ref:`superutente` che verrà automaticamente creato qualora il database non contenga altri utenti. -.. code-block:: yml +.. code-block:: yaml - DJANGO_SU_USERNAME=root @@ -173,7 +173,7 @@ Specifica il nome del :ref:`superutente` che verrà automaticamente creato qualo Specifica l'email del :ref:`superutente` che verrà automaticamente creato qualora il database non contenga altri utenti. -.. code-block:: yml +.. code-block:: yaml - DJANGO_SU_USERNAME=bot@steffo.eu @@ -187,7 +187,7 @@ Specifica l'email del :ref:`superutente` che verrà automaticamente creato qualo Specifica la password del :ref:`superutente` che verrà automaticamente creato qualora il database non contenga altri utenti. -.. code-block:: yml +.. code-block:: yaml - DJANGO_SU_PASSWORD=square @@ -203,7 +203,7 @@ Specifica il valore con cui precompilare il campo "selezione istanza" dell'inter Eccetto in configurazioni speciali, deve essere uguale al dominio prefisso dal protocollo e da ``api.``. -.. code-block:: yml +.. code-block:: yaml - REACT_APP_DEFAULT_INSTANCE=https://api.ilmiosophon.it @@ -213,7 +213,7 @@ Eccetto in configurazioni speciali, deve essere uguale al dominio prefisso dal p Specifica il dominio che dovrà essere usato come radice per il proxy, ovvero il ``DOMINIO`` per il quale si è configurato il DNS in precedenza. -.. code-block:: yml +.. code-block:: yaml - APACHE_PROXY_BASE_DOMAIN=dev.sophon.steffo.eu diff --git a/docs/source/3_dev/2_structure/1_backend/index.rst b/docs/source/3_dev/2_structure/1_backend/index.rst index fe5cc80..7c2e0fe 100644 --- a/docs/source/3_dev/2_structure/1_backend/index.rst +++ b/docs/source/3_dev/2_structure/1_backend/index.rst @@ -45,10 +45,100 @@ Struttura del modulo Il modulo consiste nel package Python :mod:`sophon`, che contiene al suo interno un progetto Django, che a sua volta contiene tre app Django. + Il progetto `sophon` ^^^^^^^^^^^^^^^^^^^^ .. module:: sophon +Il progetto Django Sophon aggiunge varie funzionalità al template base dei progetti Django. + + +Pagina di amministrazione personalizzata +"""""""""""""""""""""""""""""""""""""""" + +.. module:: sophon.admin + +.. class:: SophonAdminSite(django.contrib.admin.AdminSite) + + La pagina di amministrazione viene personalizzata con la classe `SophonAdminSite`, che sovrascrive alcuni parametri della classe di default. + + Inoltre, il template predefinito viene sovrascritto da quello all'interno del file ``templates/admin/base.html``, che sostituisce il foglio di stile con uno personalizzato per Sophon. + + .. attribute:: site_header = "Sophon Server Administration" + + Il nome della pagina nell'header viene modificato a *Sophon Server Administration*. + + .. attribute:: site_title = "Sophon Server Administration" + + Il titolo della pagina nell'header viene anch'esso modificato a *Sophon Server Administration*. + + .. attribute:: site_url = None + + Il collegamento *View Site* viene rimosso, in quanto è possibile accedere all'interfaccia web di Sophon da più domini contemporaneamente. + + .. attribute:: index_title = "Resources Administration" + + Il titolo dell'indice viene modificato a *Resources Administration*. + +.. class:: SophonAdminConfig(django.contrib.admin.apps.AdminConfig) + + La configurazione di default della pagina di amministrazione viene sovrascritta da questa classe. + + .. attribute:: default_site = "sophon.admin.SophonAdminSite" + + `.SophonAdminSite` è selezionata come classe predefinita. + + +Impostazioni dinamiche +"""""""""""""""""""""" +.. module:: sophon.settings + +Il file di impostazioni viene modificato per **permettere la configurazione attraverso variabili di ambiente** invece che attraverso il file ``settings.py``, rendendo il deployment con Docker molto più semplice. + +.. code-block:: python + + try: + DATABASE_ENGINE = os.environ["DJANGO_DATABASE_ENGINE"] + except KeyError: + log.warning("DJANGO_DATABASE_ENGINE was not set, defaulting to PostgreSQL") + DATABASE_ENGINE = "django.db.backends.postgresql" + log.debug(f"{DATABASE_ENGINE = }") + +Inoltre, viene configurato il modulo `logging` per emettere testo colorato di più facile comprensione usando il package `coloredlogs`. + +.. code-block:: python + + "detail": { + "()": coloredlogs.ColoredFormatter, + "format": "{asctime:>19} | {name:<24} | {levelname:>8} | {message}", + "style": "{", + } + + +Autenticazione migliorata +""""""""""""""""""""""""" +.. module:: sophon.auth1 + +.. class:: BearerTokenAuthentication(rest_framework.authentication.TokenAuthentication) + + La classe `rest_framework.authentication.TokenAuthentication` viene modificata per ottenere un comportamento conforme agli standard del web. + + .. attribute:: keyword = "Bearer" + + Si configura `rest_framework` per accettare header di autenticazione nella forma ``Bearer ``, invece che ``Token ``. + +.. module:: sophon.auth2 + +.. class:: CustomObtainAuthToken(rest_framework.authtoken.views.ObtainAuthToken) + + La view `rest_framework.authtoken.views.ObtainAuthToken` viene estesa per aggiungere dati alla risposta di autenticazione riuscita. + + .. method:: post(self, request, *args, **kwargs) + + In particolare, viene aggiunta una chiave ``user``, che contiene i dettagli sull'utente che ha effettuato il login. + +.. todo: whoa ma io mi ero scordato di sta cosa + L'app `sophon.core` ^^^^^^^^^^^^^^^^^^^ diff --git a/docs/source/3_dev/2_structure/index.rst b/docs/source/3_dev/2_structure/index.rst index f75db0e..778dfbd 100644 --- a/docs/source/3_dev/2_structure/index.rst +++ b/docs/source/3_dev/2_structure/index.rst @@ -4,6 +4,7 @@ Struttura del progetto Sophon è composto da quattro moduli, *backend*, *frontend*, *proxy* e *jupyter*, che interagiscono tra loro per fornire agli utenti tutti i servizi necessari. .. toctree:: + :maxdepth: 2 1_backend/index 2_frontend/index diff --git a/docs/source/conf.py b/docs/source/conf.py index d9dcf71..df1e863 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -64,6 +64,7 @@ intersphinx_mapping = { "python": ("https://docs.python.org/3.8", None), "django": ("http://docs.djangoproject.com/en/3.2/", "http://docs.djangoproject.com/en/3.2/_objects/"), "docker": ("https://docker-py.readthedocs.io/en/stable/", None), + "coloredlogs": ("https://coloredlogs.readthedocs.io/en/latest/", None), } # -- Automodule options ------------------------------------------------------