📔 Write more documentation

docs/.gitattributes

@@ -0,0 +1 @@
+*.mp4 filter=lfs diff=lfs merge=lfs -text

docs/source/1_user/1_about.rst

@@ -1,34 +1,19 @@
 Il progetto in breve
-====================
+********************
 
-*Sophon* è una applicazione web realizzata nel 2021 da Stefano Pigozzi per conto del **dipartimento di Informatica** dell'**Università di Modena e Reggio Emilia**.
+*Sophon* è una applicazione web realizzata nel 2021 da Stefano Pigozzi per conto del `dipartimento di Informatica`_ dell'`Università di Modena e Reggio Emilia`_.
 
-.. TODO: Rileggere la frase seguente.
+Sophon permette ai suoi utenti di effettuare in sicurezza attività di ricerca collaborativa da remoto, sfruttando le macchine dell'istituzione di loro appartenenza per l'elaborazione dei dati.
-
-Sophon permette ai suoi utenti di **effettuare in sicurezza attività di ricerca collaborativa da remoto, sfruttando le macchine dell'istituzione di appartenenza per l'elaborazione dei dati**.
 
+.. _dipartimento di Informatica: https://www.fim.unimore.it/
+.. _Università di Modena e Reggio Emilia: https://www.unimore.it/
 
 Screenshots
 -----------
 
 .. image:: instance_select.png
-
 .. image:: user_select.png
-
 .. image:: notebook_select.png
-
 .. image:: mode_select.png
-
 .. image:: inside_the_lab.png
-
 .. image:: admin_page.png
-
-
-Licenza
--------
-
-Sophon è rilasciato sotto la `GNU Affero General Public License 3`_ (o successiva).
-
-Il testo completo della licenza è disponibile all'interno del file ``LICENSE.txt`` allegato al codice sorgente del software.
-
-.. _GNU Affero General Public License 3: https://www.gnu.org/licenses/agpl-3.0.html

docs/source/1_user/2_concepts.rst

@@ -0,0 +1,227 @@
+I concetti
+**********
+
+Istanza
+=======
+
+Un'*istanza* rappresenta un'**installazione di Sophon** effettuata su un server di un'istituzione di ricerca, come ad esempio un'Università.
+
+Ogni istanza è **fisicamente e logicamente separata** dalle altre; istanze diverse **non condividono alcun dato** tra loro.
+
+.. image:: instances_diagram.png
+   :width: 400
+
+
+URL dell'istanza
+----------------
+
+Ciascuna istanza è accessibile tramite **uno specifico URL**, deciso dall'amministratore di sistema al momento dell'installazione.
+
+.. image:: instances_urls.png
+   :width: 400
+
+
+Istanze nell'interfaccia web
+----------------------------
+
+L'interfaccia web di Sophon permette di **selezionare l'istanza** che si desidera usare inserendo il corrispondente URL.
+
+.. image:: instance_select.png
+
+
+Personalizzazione dell'istanza
+------------------------------
+
+Nel pannello di amministrazione di un'istanza Sophon è possibile personalizzare alcuni dettagli dell'istanza, quali:
+
+- il **nome** dell'istanza, che verrà visualizzato come titolo dell'interfaccia web;
+
+  .. image:: instance_title.png
+
+- la **descrizione** dell'istanza in `Markdown`_, visualizzata all'interno del riquadro "A proposito dell'istanza";
+
+  .. image:: instance_description.png
+
+- il **tema colori** dell'istanza, applicato all'interfaccia web una volta che l'istanza è stata selezionata.
+
+  .. image:: instance_theme_sophon.png
+     :width: 240
+  .. image:: instance_theme_royalblue.png
+     :width: 240
+  .. image:: instance_theme_amber.png
+     :width: 240
+  .. image:: instance_theme_paper.png
+     :width: 240
+  .. image:: instance_theme_hacker.png
+     :width: 240
+
+
+.. _Markdown: https://it.wikipedia.org/wiki/Markdown
+
+
+Utente
+======
+
+Un *utente* è una entità che interagisce con una specifica istanza Sophon: ad esempio, un utente potrebbe essere una persona fisica, oppure potrebbe essere un software di automazione che si interfaccia con Sophon.
+
+
+Livelli di accesso
+------------------
+
+Un utente può avere uno dei seguenti livelli di accesso:
+
+.. glossary::
+
+   Superutente
+      Utente con accesso completo a ogni singola risorsa sull'istanza Sophon, tipicamente riservato per l'amministratore di sistema; deve effettuare l'accesso all'istanza con le proprie credenziali.
+
+   Utente
+      Utente con permessi limitati alle risorse che ha creato o a cui è stato fornito accesso; deve effettuare l'accesso all'istanza con le proprie credenziali.
+
+   Ospite
+      Utente che può visualizzare alcuni contenuti dell'istanza Sophon ma non può interagirci.
+
+
+Creazione di nuovi utenti
+-------------------------
+
+In una istanza Sophon, la registrazione autonoma non è possibile: ciò permetterebbe agli utenti creati di accedere a dati riservati al personale di ricerca.
+
+Nuovi utenti possono essere creati esclusivamente da un :term:`superutente` nel pannello di amministrazione dell'istanza.
+
+.. image:: user_creation.png
+
+
+Utenti nell'interfaccia web
+---------------------------
+
+L'interfaccia web di Sophon permette di **selezionare la tipologia di utente** con la quale si intende utilizzare il servizio.
+
+.. image:: user_select.png
+
+
+Gruppo di ricerca
+=================
+
+Un *gruppo di ricerca* rappresenta un insieme di :term:`utenti` che collaborano su uno o più progetti.
+
+.. image:: groups_diagram.png
+   :width: 400
+
+
+Membri dei gruppi
+-----------------
+
+Gli :term:`utenti` dell'istanza possono diventare *membri* dei gruppi di ricerca, con una delle seguenti modalità selezionate nelle impostazioni del gruppo:
+
+- se il gruppo è *aperto*, allora qualsiasi utente può diventarne membro semplicemente **facendo richiesta** attraverso l'interfaccia web;
+
+  .. image:: join_request.png
+
+- se il gruppo è in *modalità manuale*, allora nessun utente potrà richiedere di unirsi, e i membri saranno **selezionati manualmente** dal creatore del gruppo.
+
+  .. image:: join_manual.png
+
+Nell'interfaccia web, i gruppi aperti sono marcati con l'icona di un **globo 🌐**, mentre i gruppi in modalità manuale sono marcati con l'icona di una **busta ✉️**.
+
+.. image:: group_icons.png
+
+In qualsiasi momento, i membri di un gruppo possono **lasciarlo** facendo richiesta attraverso l'interfaccia web.
+
+
+Creazione di nuovi gruppi
+-------------------------
+
+Qualsiasi :term:`utente` può **creare** gruppi di ricerca dall'interfaccia web.
+
+.. image:: group_creation.png
+
+
+Modifica di gruppi
+------------------
+
+Il creatore di un gruppo di ricerca è l'unico :term:`utente` che può cambiarne **nome**, **descrizione**, **membri** e **modalità di accesso**.
+
+Lo *slug*, l'identificatore univoco del gruppo, non è modificabile successivamente alla creazione, dato che è utilizzato all'interno degli URL.
+
+
+Eliminazione di gruppi
+----------------------
+
+Il creatore di un gruppo è l'unico utente in grado di **cancellare** il gruppo che ha creato.
+
+.. warning::
+
+   L'eliminazione di un gruppo è un'operazione distruttiva non reversibile!
+
+.. note::
+
+   Se si è i creatori di un gruppo, e si vuole trasferire il gruppo ad un altro utente, sarà necessario fare richiesta ad un :term:`superutente` di cambiare il proprietario del gruppo all'interno del pannello di amministrazione.
+
+.. seealso::
+
+   :ref:`Conferma di eliminazione`
+
+
+Progetto di ricerca
+===================
+
+Un *progetto di ricerca* rappresenta una **collezione di materiali** relativa a un singolo argomento mantenuta da un :ref:`gruppo di ricerca`.
+
+.. image:: projects_diagram.png
+   :width: 400
+
+
+Creazione di nuovi progetti
+---------------------------
+
+Qualsiasi *membro* di un :ref:`gruppo di ricerca` può creare nuovi progetti.
+
+
+Modifica di progetti
+--------------------
+
+Qualsiasi *membro* di un :ref:`gruppo di ricerca` può modificare **nome**, **descrizione** dei progetti al suo interno.
+
+Solo il *creatore del gruppo* può modificarne la **visibilità**, o **trasferire il progetto ad un altro gruppo**.
+
+Lo *slug*, l'identificatore univoco del progetto, non è modificabile successivamente alla creazione, dato che è utilizzato all'interno degli URL.
+
+
+Eliminazione di progetti
+------------------------
+
+Il **creatore del gruppo** al quale appartiene il progetto è l'unico utente in grado di eliminarlo.
+
+.. warning::
+
+   L'eliminazione di un progetto è un'operazione distruttiva non reversibile!
+
+.. seealso::
+
+   :ref:`Conferma di eliminazione`
+
+
+Visibilità dei progetti
+-----------------------
+
+I progetti hanno tre diverse impostazioni di visibilità che regolano chi può visualizzarne i contenuti:
+
+.. glossary::
+
+   Progetto privato
+      Il progetto è visibile solo ai membri del gruppo a cui appartiene il progetto.
+
+   Progetto interno
+      Il progetto è visibile solo agli :term:`utenti` dell'istanza, e non agli :term:`ospiti`.
+
+   Progetto pubblico
+      Il progetto è visibile a tutti.
+
+I progetti privati sono marcati con l'icona di un **luchetto chiuso 🔒**, i progetti interni con l'icona di un **università 🏦** e i progetti pubblici con l'icona di un **globo 🌐**.
+
+
+Notebook
+========
+
+.. TODO: Do this.

docs/source/1_user/3_extras.rst

@@ -0,0 +1,11 @@
+Dettagli implementativi dell'interfaccia web
+********************************************
+
+Conferma di eliminazione
+========================
+
+Per impedire eliminazioni accidentali di risorse, è presente nell'interfaccia web un meccanismo di conferma che richiede all'utente di ripremere il tasto di eliminazione trascorsi 3 secondi dalla prima richiesta.
+
+.. raw:: html
+
+   <p><video controls src="../_static/group_delete_confirm.mp4"></video></p>

docs/source/conf.py

@@ -57,7 +57,7 @@ nitpicky = True
 html_theme = 'sphinx_rtd_theme'
 
 html_theme_options = {
-    "style_nav_header_background": "#3B7097"
+    "style_nav_header_background": "#051836"
 }
 
 # Add any paths that contain custom static files (such as style sheets) here,

docs/source/index.rst

@@ -11,7 +11,7 @@ Contenuti
    :caption: Manuale utente
 
    1_user/1_about
-   1_user/2_usage
+   1_user/2_concepts
 
 
 .. toctree::
@@ -36,3 +36,13 @@ Collegamenti
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
+
+
+Licenza
+-------
+
+Sophon è rilasciato sotto la `GNU Affero General Public License 3`_ (o successiva).
+
+Il testo completo della licenza è disponibile all'interno del file ``LICENSE.txt`` allegato al codice sorgente del software.
+
+.. _GNU Affero General Public License 3: https://www.gnu.org/licenses/agpl-3.0.html