Merge branch 'further-doc-improvements' into 'master'

[Docs] Further improvements

Closes #614, #617, and #625

See merge request !910

CHANGELOG.rst

@@ -14,6 +14,7 @@ Fixed
 
 * Migration added in 2.7.2 did not work in all scenarios
 * [Dev] Field change tracking API for Person was broken in 2.7.2
+* Add missing documentation
 
 `2.7.2`_ - 2022-01-31
 ---------------------

docs/admin/01_core_concepts.rst

@@ -4,7 +4,7 @@ Concepts of the AlekSIS core
 The AlekSIS core provides functionality and data models as a base for
 all apps.
 
-.. _sec:SchoolTerms:
+.. _core-concept-schoolterm:
 
 The concept of school terms
 ---------------------------
@@ -32,7 +32,7 @@ of all school terms and buttons to create, edit or delete school terms.
 Please be aware that there can be only one school term at time and each
 school term needs a unique name.
 
-.. _sec:Persons:
+.. _core-concept-person:
 
 The concept of persons
 ----------------------
@@ -49,7 +49,7 @@ information like the following:
 -  Address details
 -  Photo
 -  Relation to guardians
--  Primary group (e. g. a class or a tutor group, cf. [@sec:Groups])
+-  Primary group (e. g. a class or a tutor group, cf. :ref:`core-concept-group`)
 
 Except for the name, all data points are optional, so you can decide on
 your own (and based on your local data protection laws) which data should be
@@ -74,7 +74,7 @@ The main method to manage persons is the view under
 ``People → Persons``. To add person to groups, you have to open the
 respective group and set the person as a member or an owner.
 
-.. _sec:Groups:
+.. _core-concept-group:
 
 The concept of groups
 ---------------------
@@ -95,18 +95,20 @@ class or a course varies from school term to school term. In order to
 archive historical data according to local laws, these groups have to be
 separeted which is solved by linking them to a school term.
 
-Manage group types
-~~~~~~~~~~~~~~~~~~
-
-You can manage your local group types by opening the menu entry
-``People → Group types`` as an admin user.
-
 Manage groups
 ~~~~~~~~~~~~~
 
 Groups are managed on the page ``People → Groups``. There you can
 search, view, create, change and delete groups.
 
+.. _core-concept-grouptype:
+
+Manage group types
+~~~~~~~~~~~~~~~~~~
+
+You can manage your local group types by opening the menu entry
+``People → Group types`` as an admin user.
+
 Import school terms, persons and groups from other data sources
 ---------------------------------------------------------------
 

docs/admin/02_install.rst → docs/admin/10_install.rst

@@ -20,6 +20,8 @@ AlekSIS will need and use the following paths:
 
 You can change any of the paths as you like.
 
+.. _core-install-prerequisites:
+
 Prerequisites
 ~~~~~~~~~~~~~
 
@@ -123,6 +125,8 @@ from `yarnpkg`, collect static files, and migrate the database to the final sche
    aleksis-admin migrate
    aleksis-admin createinitialrevisions
 
+.. _core-configure-uwsgi:
+
 Configure uWSGI
 ~~~~~~~~~~~~~~~
 

docs/admin/02_config.rst → docs/admin/15_config_files.rst

+.. _core-configuration-files:
+
 Configuration files and format
 ==============================
 

docs/admin/18_mail.rst

+Mail
+====
+
+AlekSIS needs to send mails e.g. for account confirmations, feedback or
+error reports.
+
+Configure mailing
+-----------------
+
+The mailserver can be configured via the configuration file
+
+.. code-block:: toml
+
+	[mail.server]
+	host = "mail.example.com"
+	tls = False
+	ssl = True
+	port = 25
+	user = "mailuser"
+	password = "password"
+
+Name and address for mails sent by AlekSIS can be configured in the
+webinterface.  To configure, visit `Admin → Configuration` and click on the
+`Mail` tab.
+
+Configure mail recipients
+-------------------------
+
+You can configure admin contacts in your configuration file, located at
+``/etc/aleksis/``.
+
+.. code-blocK:: toml
+
+	[contact]
+	admins = [["AlekSIS - Admins", "root@example.com"],["AlekSIS - Admins2", "root2@example.com"]]
+	from = 'aleksis@example.com'

docs/admin/03_ldap.rst → docs/admin/21_ldap.rst

+.. _core-ldap:
+
 Authenticating against LDAP
 ===========================
 

docs/admin/22_registration.rst

+Registration and user invitations
+=================================
+
+In addition to central management of user accounts, AlekSIS allows self-registration
+by users. Registration can be either fully open, or based on personal invitations.
+
+In a system handling ciritcal data, access control should be as tight as possible.
+However, there are scenarios where central account creation is not feasible, e.g.
+for optional guardian accounts. In such a scenario, the invitation system allows
+for processes like handing out invitation codes as a letter or through e-mail
+campaigns.
+
+Configuration
+-------------
+
+.. _core-registration:
+
+Registration
+~~~~~~~~~~~~
+
+Registration can be enabled via the configuration interface in frontend.
+
+In the ``Authentication`` tab, click the checkbox ``Enable signup`` to enable
+signup for everyone. A menu item will be added for public registration.
+
+.. warning::
+   Do not enable this feature unless you intend to run a public AlekSIS instance.
+
+User invitations
+~~~~~~~~~~~~~~~~
+
+.. _core-user-invitations:
+
+In the same location as public registration, the invitation system can be enabled.
+
+* Authentication
+
+  * Enable invitations: Click to enable invitations.
+  * Length of invite code: Length of invitation code packets, defaults to 5.
+  * Size of packets: Configure how many packets are generated, defaults to 3.
+
+By default, an invitation code looks like the following:
+``abcde-abcde-abcde``.
+
+A menu item will become available for users to enter their invitation code.
+
+Usage
+-----
+
+Invite by email or code
+~~~~~~~~~~~~~~~~~~~~~~~
+
+To invite a new user , visit the invitation page located at ``People → Invite
+person``
+
+Here you are able to invite the user by email address or generate an
+invitation code.
+
+.. image:: ../_static/invitations.png
+  :width: 100%
+  :alt: Invitations page
+
+This mechanism allows for registration of entirely new persons that do not
+exist in the system, e.g. if perosnal details are not known in advance.
+
+Invite existing person
+~~~~~~~~~~~~~~~~~~~~~~
+
+To invite an existing person, open the person in AlekSIS and click ``Invite
+user``.
+
+The invitation will be sent to the person's email address, and can only
+be used by this person. Upon registration, the new account will automatically
+be linked to the existing person.
+
+.. image:: ../_static/invite_existing.png
+  :width: 100%
+  :alt: Invite existing person
+
+.. note::
+   Before using this feature, make sure to read and understand
+   :ref:`core-concept-person`.

docs/admin/04_socialaccounts.rst → docs/admin/23_socialaccounts.rst

@@ -34,5 +34,5 @@ provider and enter client id and secret from your application and choose
 your site:
 
 .. image:: ../_static/create_social_application.png
-  :width: 400
+  :width: 100%
   :alt: Create social application

docs/admin/32_tasks.rst

+Background tasks
+================
+
+Operations that are expected to take a long time are run as background tasks.
+For this, at least one `Celery`_ worker has to be running, e.g. by coupling it
+with uWSGI as laid out in :ref:`core-configure-uwsgi`.
+
+If a task is triggered from the AlekSIS frontend, for example by starting an import
+job, a progress page is displayed, and the result of the job is waited for.
+
+.. _core-periodic-tasks:
+
+Periodic tasks
+~~~~~~~~~~~~~~
+
+Some tasks are also run on a schedule. For example, the backup job is run on
+a regular basis.
+
+All tasks in AlekSIS that are expected to run have a default schedule, which
+is registered when migrating the database. Changing this default schedule
+is currently only possible through the Django Admin backend, under
+*Admin → Backend Admin*.
+
+Under the *Periodic Tasks* app, you can define schedules and tasks. The names
+of tasks you can add manually are documented in the respective sections
+of the manual.

docs/admin/33_data_checks.rst

+.. _core-data-checks:
+
+Data checks
+===========
+
+Data checks are AlekSIS' mechanism for highlighting issues with the
+contents of the database. These checks are not of a technical nature,
+but strictly concern the contextual integrity of the data stored.
+
+
+Verify data checks
+------------------
+
+In the menu under ``Admin → Data checks``, the status of all known
+checks can be verified.
+
+.. image:: ../_static/data_checks.png
+   :width: 100%
+   :alt: Data check overview
+
+The first card shows the current global check state. If any data checks
+reported issues, they will be listed here. In that case, administrators can
+choose between options provided by the data checks to resolve the issues.
+
+.. note::
+   Details about the checks and solve options are described in the
+   respective chapters of the manual.
+
+Configure notifications
+-----------------------
+
+In the ``General`` tab of the configuration interface, you can configure
+email notifications for problems detected by the data checks.
+
+* General
+
+  * Send emails if data checks detect problems: Enable email notifications
+  * Email recipients for data checks problem emails: Choose recipient persons
+  * Email recipient groups for data checks problem emails: Choose recipient groups
+
+Data checks normally run once per hour, and if notifications are enabled, results
+will be mailed to the selected recipients if problems are detected.

docs/dev/06_merging_app_settings.rst

@@ -23,7 +23,3 @@ the following into your ``settings.py``::
             "HOST": "127.0.0.1",
             "PORT": 5432,
         }
-
-If you install new apps and want to configure these, or need some other settings you can easily add
-settings to your ``settings.py``.  Only settings that do not exist in the
-main ``settings.py`` will be respected.

docs/user/01_registration.rst

+Register a new account
+======================
+
+.. _core-user-registration:
+
+Public registration
+-------------------
+
+If public registration is enabled on the AlekSIS instance, you can click the
+``Signup`` button located in the navigation sidebar and register for an
+AlekSIS account.
+
+.. image:: ../_static/signup.png
+  :width: 100%
+  :alt: Signup formular
+
+If enabled, you have to verify your email address after signup. To do so, click
+on the link you recieved on the email address you entered in the signup form.
+
+.. note::
+   Normally, AlekSIS does not allow public registratio, and all accounts are
+   centrally managed by administrators. Public registration is an optional
+   feature that has to be enabled by adminsitrators after careful consideration.
+
+Using an invitation code
+------------------------
+
+If you have an invitation code, click ``Accept invitation`` in the sidebar and
+enter it. You will be redirected to the signup form.
+
+.. image:: ../_static/accept_invite.png
+  :width: 100%
+  :alt: Accept invitation
+
+If you've recieved an invitation link (e.g. via email), clicking the link
+will redirect you to the signup form automatically.