diff --git a/docs/.gitattributes b/docs/.gitattributes new file mode 100644 index 0000000..f8ff2b5 --- /dev/null +++ b/docs/.gitattributes @@ -0,0 +1 @@ +*.mp4 filter=lfs diff=lfs merge=lfs -text diff --git a/docs/source/1_user/1_about.rst b/docs/source/1_user/1_about.rst index 1080dbf..c35f2bf 100644 --- a/docs/source/1_user/1_about.rst +++ b/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 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 loro 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 \ No newline at end of file diff --git a/docs/source/1_user/2_concepts.rst b/docs/source/1_user/2_concepts.rst new file mode 100644 index 0000000..2227ad6 --- /dev/null +++ b/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. diff --git a/docs/source/1_user/2_usage.rst b/docs/source/1_user/2_usage.rst deleted file mode 100644 index e69de29..0000000 diff --git a/docs/source/1_user/3_extras.rst b/docs/source/1_user/3_extras.rst new file mode 100644 index 0000000..c2caf69 --- /dev/null +++ b/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 + +

diff --git a/docs/source/1_user/admin_login.png b/docs/source/1_user/admin_login.png new file mode 100644 index 0000000..0b51e45 --- /dev/null +++ b/docs/source/1_user/admin_login.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:1e5c1c88b99011e1bf095b9136450d332a703421b9178e9af00f9f4edae977fe +size 7900 diff --git a/docs/source/1_user/group_creation.png b/docs/source/1_user/group_creation.png new file mode 100644 index 0000000..015baf0 --- /dev/null +++ b/docs/source/1_user/group_creation.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:1c55e19a3bd346d93ab74d1fa64c19640dda604edf85594cc294af5b70f9344b +size 29389 diff --git a/docs/source/1_user/group_icons.png b/docs/source/1_user/group_icons.png new file mode 100644 index 0000000..27741ca --- /dev/null +++ b/docs/source/1_user/group_icons.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:14dd8467d2cb74c628c84101452f943c2138821c755e72171914d31a5279948a +size 17782 diff --git a/docs/source/1_user/groups_diagram.png b/docs/source/1_user/groups_diagram.png new file mode 100644 index 0000000..189e7c6 --- /dev/null +++ b/docs/source/1_user/groups_diagram.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:199492ba18145d93589f0f7f341a11b03a39e1b1c5e68ddd344fd44f3978e373 +size 75195 diff --git a/docs/source/1_user/instance_description.png b/docs/source/1_user/instance_description.png new file mode 100644 index 0000000..c60d183 --- /dev/null +++ b/docs/source/1_user/instance_description.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:fd836dbca80ebf6276dcc78bc57af6ab52469c0b6530fc059d0c15a2e68263ff +size 10769 diff --git a/docs/source/1_user/instance_theme_amber.png b/docs/source/1_user/instance_theme_amber.png new file mode 100644 index 0000000..e718dbe --- /dev/null +++ b/docs/source/1_user/instance_theme_amber.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:29a83246fdbde1f4da79079941eff2f6787634aeb0e9ca6890e3869637033950 +size 87539 diff --git a/docs/source/1_user/instance_theme_hacker.png b/docs/source/1_user/instance_theme_hacker.png new file mode 100644 index 0000000..f866aa3 --- /dev/null +++ b/docs/source/1_user/instance_theme_hacker.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:30280a0d7cb11872d53808b23321a6dceda327846df916499cb0686d8fa18ad7 +size 92360 diff --git a/docs/source/1_user/instance_theme_paper.png b/docs/source/1_user/instance_theme_paper.png new file mode 100644 index 0000000..9ddc34a --- /dev/null +++ b/docs/source/1_user/instance_theme_paper.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:1e9387183c87e6e975e3b29f8c20c2cb54a0d8ccde92283dc879e7e27657d1cb +size 93038 diff --git a/docs/source/1_user/instance_theme_royalblue.png b/docs/source/1_user/instance_theme_royalblue.png new file mode 100644 index 0000000..389cc0a --- /dev/null +++ b/docs/source/1_user/instance_theme_royalblue.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:cb4732d43c7beaae086b3706aee975630368c89dbb40e5c443741cc1a118d097 +size 89961 diff --git a/docs/source/1_user/instance_theme_sophon.png b/docs/source/1_user/instance_theme_sophon.png new file mode 100644 index 0000000..8549c20 --- /dev/null +++ b/docs/source/1_user/instance_theme_sophon.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:196420450f19e73fac5e8f2ce6c1862c66fe918f9e42adc128351d82f5ed9145 +size 90746 diff --git a/docs/source/1_user/instance_title.png b/docs/source/1_user/instance_title.png new file mode 100644 index 0000000..8b063b4 --- /dev/null +++ b/docs/source/1_user/instance_title.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:694b3d936312e51d3c4d3f74d9aca45c9eed8e60d1600020fd42b93081c6d509 +size 4046 diff --git a/docs/source/1_user/instances_diagram.png b/docs/source/1_user/instances_diagram.png new file mode 100644 index 0000000..f8f3dc1 --- /dev/null +++ b/docs/source/1_user/instances_diagram.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b724c49caa314083dddd914727d6b2c718cb50a9104635b09c7055cec7deefa6 +size 22041 diff --git a/docs/source/1_user/instances_urls.png b/docs/source/1_user/instances_urls.png new file mode 100644 index 0000000..03f62a0 --- /dev/null +++ b/docs/source/1_user/instances_urls.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:81424ecf1442787418deca201cca953b1c63fa80fff68c3637bcf52c27d8a091 +size 78677 diff --git a/docs/source/1_user/join_manual.png b/docs/source/1_user/join_manual.png new file mode 100644 index 0000000..bc576ba --- /dev/null +++ b/docs/source/1_user/join_manual.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c116a160f21ebf9b3bd38c5775ebe442d1b97c9ff74f0dabd441b37036a234a1 +size 3388 diff --git a/docs/source/1_user/join_request.png b/docs/source/1_user/join_request.png new file mode 100644 index 0000000..a51955e --- /dev/null +++ b/docs/source/1_user/join_request.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:40dd1d443c4215308de6baddaaae7b70c19174be02cfbd96ef24e135c7dbce1e +size 1104 diff --git a/docs/source/1_user/projects_diagram.png b/docs/source/1_user/projects_diagram.png new file mode 100644 index 0000000..2407086 --- /dev/null +++ b/docs/source/1_user/projects_diagram.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:0b8a81e60a0aff1a91182ea7614fc782c89612a857f6234d12ad92e53ba83a25 +size 43109 diff --git a/docs/source/1_user/user_creation.png b/docs/source/1_user/user_creation.png new file mode 100644 index 0000000..c50c404 --- /dev/null +++ b/docs/source/1_user/user_creation.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:15680a4cd5e988c57010e5b02cc281d6b7756fa371c46e50035365205a3f41dd +size 29373 diff --git a/docs/source/1_user/user_select.png b/docs/source/1_user/user_select.png index 3f03690..8549c20 100644 --- a/docs/source/1_user/user_select.png +++ b/docs/source/1_user/user_select.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:052b06e0de690c235deaa8cdb19dd65a764c00d729fd8852aa3feacb85977888 -size 92018 +oid sha256:196420450f19e73fac5e8f2ce6c1862c66fe918f9e42adc128351d82f5ed9145 +size 90746 diff --git a/docs/source/_static/group_delete_confirm.mp4 b/docs/source/_static/group_delete_confirm.mp4 new file mode 100644 index 0000000..06ab00f --- /dev/null +++ b/docs/source/_static/group_delete_confirm.mp4 @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:f4a834868c351f5cfaf99c7f78c2ed5b7aaa458fe444c69a3d0c9c1c56ab0993 +size 75562 diff --git a/docs/source/conf.py b/docs/source/conf.py index 88995d6..2200ceb 100644 --- a/docs/source/conf.py +++ b/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, diff --git a/docs/source/index.rst b/docs/source/index.rst index d96ff91..a85be52 100644 --- a/docs/source/index.rst +++ b/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