diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index a4349087629ec1c1a04444327e503b6b775cbc4b..564449be1717a97282b53b2d94f9f234b34261c2 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -19,5 +19,3 @@ include:
file: "/ci/deploy/review.yml"
- project: "AlekSIS/official/AlekSIS"
file: "/ci/deploy/trigger_dist.yml"
- - project: "AlekSIS/official/AlekSIS"
- file: /ci/deploy/pages.yml
diff --git a/docs/_static/2fa.png b/docs/_static/2fa.png
new file mode 100644
index 0000000000000000000000000000000000000000..e8d35aaf19e56df08c5cbf0fdafdfd7c63d2d0fe
Binary files /dev/null and b/docs/_static/2fa.png differ
diff --git a/docs/admin/00_index.rst b/docs/admin/00_index.rst
index 3c60f9d9540f1bba978f665cdd0c342160d6a2e1..b41aee2b80bc0d58181ca8374e696bb5a265cc44 100644
--- a/docs/admin/00_index.rst
+++ b/docs/admin/00_index.rst
@@ -1,5 +1,5 @@
-Configuration and administration
-================================
+Setup of the AlekSIS instance and the AlekSIS core
+==================================================
.. toctree::
:glob:
diff --git a/docs/admin/01_core_concepts.rst b/docs/admin/01_core_concepts.rst
new file mode 100644
index 0000000000000000000000000000000000000000..680ee618367334efff3cde1befcf082d9fdeb8f2
--- /dev/null
+++ b/docs/admin/01_core_concepts.rst
@@ -0,0 +1,115 @@
+Concepts of the AlekSIS core
+============================
+
+The AlekSIS core provides functionality and data models as a base for
+all apps.
+
+.. _sec:SchoolTerms:
+
+The concept of school terms
+---------------------------
+
+In AlekSIS, mostly everything is based on school terms. A school term is
+a defined time range which can be used to link data to it. Typically,
+such data are learning groups, timetables or class register records.
+Although their name suggests it, school terms don’t have to be a half or
+a full year. They should depend on the way how you organise data in your
+institution.
+
+For example, if you issue reports at the end of every half year, a half
+year would be a good time range for your school terms because the class
+register statistics are evaluated for school terms.
+
+Anyway, you should create a school term before you start to import or
+create other data entries like persons or groups.
+
+Manage school terms
+~~~~~~~~~~~~~~~~~~~
+
+You can manage the school terms if you login with your admin account and
+open the menu entry ``Admin → School terms``. There you can find a list
+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:
+
+The concept of persons
+----------------------
+
+The person model is designed to save all the data of students, teachers,
+guardians and any other persons of the school society. It tracks
+information like the following:
+
+- Full name
+- Short name
+- Sex
+- Date of birth
+- Contact details (phone numbers, email)
+- Address details
+- Photo
+- Relation to guardians
+- Primary group (e. g. a class or a tutor group, cf. [@sec:Groups])
+
+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
+included in AlekSIS.
+
+There are two important things you should know about persons:
+
+- **Persons are not automatically users:** That means that persons can
+ be linked to a user account including things like a password and the
+ ability to login, but they don’t have to be. For example, your
+ AlekSIS instance could save the data about parents, but you don’t
+ want them to login: In this scenario, the guardians are available as
+ persons **without** user accounts.
+- **Persons are not linked to school terms:** As persons like students
+ are not only at the school for one school term, persons are not
+ linked to school terms.
+
+Manage persons
+~~~~~~~~~~~~~~
+
+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:
+
+The concept of groups
+---------------------
+
+The AlekSIS groups are a universal way to organise persons in
+collections like classes, courses, tutor groups, clubs, or any other
+division you could imagine. They track the following data:
+
+- Group name and short name
+- Owners (e. g. class or course teacher(s))
+- Members (e. g. students)
+- Parent groups (e. g. a class could be a parent group for a course)
+- Group type (e. g. class, course, club, etc.)
+
+In contrast to persons, groups are supposed to be **linked to school
+terms** (but they don’t have to be). For example, the composition of a
+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.
+
+Import school terms, persons and groups from other data sources
+---------------------------------------------------------------
+
+When AlekSIS is not your single date source, all these data can be
+imported from other sources. You can find further information in the
+respective integration apps.
diff --git a/docs/admin/01_config.rst b/docs/admin/02_config.rst
similarity index 100%
rename from docs/admin/01_config.rst
rename to docs/admin/02_config.rst
diff --git a/docs/admin/01_install.rst b/docs/admin/02_install.rst
similarity index 99%
rename from docs/admin/01_install.rst
rename to docs/admin/02_install.rst
index 6d1984b96e103d90d33496f4e520b7049e748a1a..5c5b0931917447fdf8468cb1377a7aab01978e5c 100644
--- a/docs/admin/01_install.rst
+++ b/docs/admin/02_install.rst
@@ -46,9 +46,7 @@ Install some packages from the Debian package system.
nginx-full \
python3 \
python3-dev \
- libldap2-dev \
libpq-dev \
- libsasl2-dev \
yarnpkg \
python3-virtualenv \
chromium \
diff --git a/docs/admin/02_ldap.rst b/docs/admin/03_ldap.rst
similarity index 95%
rename from docs/admin/02_ldap.rst
rename to docs/admin/03_ldap.rst
index b8fbd657dedc3d3e7a6ef04a7fa36d9b7f1b66bf..795c9d5e1e1cba76dde168f9778bd12ec9178563 100644
--- a/docs/admin/02_ldap.rst
+++ b/docs/admin/03_ldap.rst
@@ -20,7 +20,7 @@ very straightforward under all circumstances. On Debian, install these packages:
Configuration of LDAP support
-----------------------------
-Configuration is done under the ``default.ldap`` section in AlekSIS’
+Configuration is done under the ``ldap`` section in AlekSIS’
configuration file. For example, add something like the following to your
configuration (normally in ``/etc/aleksis``; you can either append to an
existing file or add a new one)::
diff --git a/docs/admin/04_monitoring.rst b/docs/admin/04_monitoring.rst
deleted file mode 100644
index 1b80a43be057a285d223be803bc347ae2758fdc4..0000000000000000000000000000000000000000
--- a/docs/admin/04_monitoring.rst
+++ /dev/null
@@ -1,39 +0,0 @@
-Monitoring
-##########
-
-Prometheus
-**********
-
-AlekSIS provides a metric endpoint at `/metrics`, so you can scrape metrics in
-your Prometheus instance.
-
-Available metrics
-=================
-
-The exporter provides metrics about responses and requests, e.g. statistics
-about response codes, request latency and requests per view. It also
-provides data about database operations.
-
-Prometheus config to get metrics
-================================
-
-To get metrics of your AlekSIS instance, just add the following to your
-`prometheus.yml`::
-
- - job_name: aleksis
- static_configs:
- - targets: ['my.aleksis-instance.com']
- metrics_path: /metrics
-
-
-Grafana
-*******
-
-Visualise metrics with Grafana
-==============================
-
-If you want to visualise your AlekSIS metrics with Grafana, you can use one
-of the public available Grafana dashboards, for example the following one,
-or just write your own.
-
-https://grafana.com/grafana/dashboards/9528
diff --git a/docs/admin/03_socialaccounts.rst b/docs/admin/04_socialaccounts.rst
similarity index 80%
rename from docs/admin/03_socialaccounts.rst
rename to docs/admin/04_socialaccounts.rst
index 97b023947a27768b825c693b7c5cd8bff938a49e..b53c0f23fc69aa893004608b5c67ec8b5b740a15 100644
--- a/docs/admin/03_socialaccounts.rst
+++ b/docs/admin/04_socialaccounts.rst
@@ -4,6 +4,10 @@ Social accounts
AlekSIS can authenticate users against third party applications using OAuth2
or OpenID.
+This can be used to grant access to persons whose credentials shall not be
+managed in AlekSIS itself, for example because another authentication provider
+is already used throughout the school, or for guardians that can or should for
+some reason not get an LDAP account, or similar situations.
.. warning::
Social accounts are **not** working with two factor authentication! If a user
diff --git a/docs/admin/05_monitoring.rst b/docs/admin/05_monitoring.rst
new file mode 100644
index 0000000000000000000000000000000000000000..1847297352a135aafdff954d98eb2a2cc1a69573
--- /dev/null
+++ b/docs/admin/05_monitoring.rst
@@ -0,0 +1,113 @@
+.. _sec:Monitoring:
+
+Monitoring and health checks
+============================
+
+Configuration
+-------------
+
+Thresholds
+~~~~~~~~~~
+
+Thresholds for health checks can be configured via config file
+(``/etc/aleksis``).
+
+.. code:: toml
+
+ [health]
+ disk_usage_max_percent = 90
+ memory_min_mb = 500
+
+ [backup.database]
+ check_seconds = 7200
+
+ [backup.media]
+ check_seconds = 7200
+
+Status page
+-----------
+
+AlekSIS' status page shows information about the health of your AlekSIS
+instance. You can visit it via the left navigation bar (Admin → Status).
+
+The page shows information about debug and maintenance mode, a summary of
+your health checks and the last exit status of your celery tasks. This
+page can not be used as a health check, it will always return HTTP 200
+if the site is reachable.
+
+Health check
+------------
+
+The health check can be used to verify the health of your AlekSIS
+instance. You can access it via the browser
+(https://aleksis.example.com/health/) and it will show you a summary of
+your health checks. If something is wrong it will return HTTP 500.
+
+It is also possible to get a JSON response from the health check, for
+example via ``curl``. You only have to pass a valid
+``Accept: application/json`` header to your request.
+
+The health check can also be executed via ``aleksis-admin``:
+
+.. code:: shell
+
+ $ aleksis-admin health_check
+
+Monitoring with Icinga2
+-----------------------
+
+As already mentioned, there is a JSON endpoint at
+https://aleksis.example.com/health/. You can use an json check plugin to
+check seperate health checks or just use a HTTP check to check if the
+site returns HTTP 200.
+
+Performance monitoring with Prometheus
+--------------------------------------
+
+AlekSIS provides a Prometheus exporter. The exporter provides metrics
+about responses and requests, e.g. about response codes, request
+latency and requests per view. It also provides data about database
+operations.
+
+The metrics endpoint can be found at
+https://aleksis.example.com/metrics. In the default configuration it can
+be scraped from everywhere. You might want to add some webserver
+configuration to restrict access to this url.
+
+To get metrics of your AlekSIS instance, just add the following to
+``prometheus.yml``
+
+.. code:: yaml
+
+ - job_name: aleksis
+ static_configs:
+ - targets: ['aleksis.example.com']
+ metrics_path: /metrics
+
+Rules for prometheus alertmanager
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you are using the prometheus alertmanager, it is possible to create
+some alerting rules so that an alert is fired when your AlekSIS instance
+is slow or something.
+
+.. code:: yaml
+
+ groups:
+ - name: aleksis
+ rules:
+ - alert: HighRequestLatency
+ expr: histogram_quantile(0.999, sum(rate(django_http_requests_latency_seconds_by_view_method_bucket{instance="YOUR-INSTANCE",view!~"prometheus-django-metrics|healthcheck"}[15m])) by (job, le)) < 30
+ for: 15m
+ labels:
+ severity: page
+ annotations:
+ summary: High request latency for 15 minutes
+
+Grafana dashboard
+~~~~~~~~~~~~~~~~~
+
+There is a Grafana dashboard available to visualise the metrics.
+
+The dashboard is available at
+https://grafana.com/grafana/dashboards/9528.
diff --git a/docs/admin/05_storage.rst b/docs/admin/05_storage.rst
deleted file mode 100644
index b9b67e698c158ef6ea0b3ad2819ccd753ff9aea0..0000000000000000000000000000000000000000
--- a/docs/admin/05_storage.rst
+++ /dev/null
@@ -1,23 +0,0 @@
-Storage
-##########
-
-Amazon S3
-*********
-
-AlekSIS allows you to configure an Amazon S3 endpoint for static and media
-files. This is useful e.g. for loadbalancing with multiple AlekSIS
-instances.
-
-Configure an S3 endpoint
-=======================
-
-If you want to use an S3 endpoint to store files you have to configure the
-endpoint in your configuration file (`/etc/aleksis/aleksis.toml`)::
-
- # Default values
- [storage.s3]
- enabled = true
- endpoint_url = "https://minio.example.com"
- bucket_name = "aleksis-test"
- access_key_id = "XXXXXXXXXXXXXX"
- secret_key = "XXXXXXXXXXXXXXXXXXXXXX"
diff --git a/docs/admin/05_configuration_options.rst b/docs/admin/06_configuration_options.rst
similarity index 92%
rename from docs/admin/05_configuration_options.rst
rename to docs/admin/06_configuration_options.rst
index 19321db371728406086e35e3a4d7dd1e6979f367..d87d2a3c6a7054ae847684019817f74a1324bab5 100644
--- a/docs/admin/05_configuration_options.rst
+++ b/docs/admin/06_configuration_options.rst
@@ -63,6 +63,6 @@ Example configuration file::
Configuration in frontend
-------------------------
-Everything that must not be configured before the AlekSIS instance fully starts can be configured in frontend, such as site title and logo.
+Everything that does not have to be configured before the AlekSIS instance fully starts can be configured in frontend, such as site title and logo.
You can find the configuration options in your AlekSIS instance under ``Admin → Configuration``.
diff --git a/docs/admin/06_storage.rst b/docs/admin/06_storage.rst
new file mode 100644
index 0000000000000000000000000000000000000000..96b789b36d30e7d0014bc19df091b86d1433118a
--- /dev/null
+++ b/docs/admin/06_storage.rst
@@ -0,0 +1,43 @@
+Storage
+=======
+
+AlekSIS needs a writable storage, both for media files (pictures,
+generated PDF files, and the like), and to store generated frontend
+assets like the themed CSS stylesheet.
+
+.. note::
+ Everything except this media storage can be mounted and used
+ entirely read-only, i.e. to keep the AlekSIS installation immutable.
+
+Local filesystem storage
+------------------------
+
+By default, the media storage resides in the local filesystem, in the
+location defined in the ``static.root`` configuration key.
+
+.. warning::
+ Do not expose the media storage directly through a webserver.
+ AlekSIS uses a specially protected storage framework that
+ employs cryptographic tokens to protect user data from URL
+ guessing.
+
+Amazon S3 (or other S#-compatible storage)
+------------------------------------------
+
+AlekSIS allows you to configure an Amazon S3 endpoint for media
+files. This is useful e.g. for loadbalancing with multiple AlekSIS
+instances.
+
+Configure an S3 endpoint
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you want to use an S3 endpoint to store files you have to configure the
+endpoint in your configuration file (`/etc/aleksis/aleksis.toml`)::
+
+ # Default values
+ [storage.s3]
+ enabled = true
+ endpoint_url = "https://minio.example.com"
+ bucket_name = "aleksis-test"
+ access_key_id = "XXXXXXXXXXXXXX"
+ secret_key = "XXXXXXXXXXXXXXXXXXXXXX"
diff --git a/docs/appendix/00_index.rst b/docs/appendix/00_index.rst
new file mode 100644
index 0000000000000000000000000000000000000000..f41fee01de96a538c8e8ed94b47748d8aedee818
--- /dev/null
+++ b/docs/appendix/00_index.rst
@@ -0,0 +1,7 @@
+Appendices of AlekSIS-Core
+==========================
+
+.. toctree::
+ :glob:
+
+ *
diff --git a/docs/appendix/99_eupl.rst b/docs/appendix/99_eupl.rst
new file mode 120000
index 0000000000000000000000000000000000000000..d629c8d0995a1bcc76815b310be7e3a325daab6a
--- /dev/null
+++ b/docs/appendix/99_eupl.rst
@@ -0,0 +1 @@
+../../LICENCE.rst
\ No newline at end of file
diff --git a/docs/conf.py b/docs/conf.py
index ae443be4f16522142ae71e451bad364ae6cd7936..8ba336abc4e90072bacd0a75fec66c2d61cc4a71 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -24,14 +24,14 @@ django.setup()
# -- Project information -----------------------------------------------------
-project = "AlekSIS"
-copyright = "2019, 2020, AlekSIS team"
-author = "AlekSIS team"
+project = "AlekSIS-Core"
+copyright = "2019-2022 The AlekSIS team"
+author = "The AlekSIS Team"
# The short X.Y version
-version = "2.2"
+version = "2.5"
# The full version, including alpha/beta/rc tags
-release = "2.2"
+release = "2.5.1.dev0"
# -- General configuration ---------------------------------------------------
@@ -111,7 +111,7 @@ html_static_path = ["_static"]
# -- Options for HTMLHelp output ---------------------------------------------
# Output file base name for HTML help builder.
-htmlhelp_basename = "AlekSISdoc"
+htmlhelp_basename = f"{project}doc"
# -- Options for LaTeX output ------------------------------------------------
@@ -135,7 +135,7 @@ latex_elements = {
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
- (master_doc, "AlekSIS.tex", "AlekSIS Documentation", "AlekSIS team", "manual"),
+ (master_doc, f"{project}.tex", f"{project} Documentation", author, "manual"),
]
@@ -143,7 +143,7 @@ latex_documents = [
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
-man_pages = [(master_doc, "aleksis", "AlekSIS Documentation", [author], 1)]
+man_pages = [(master_doc, "aleksis", f"{project} Documentation", [author], 1)]
# -- Options for Texinfo output ----------------------------------------------
@@ -154,10 +154,10 @@ man_pages = [(master_doc, "aleksis", "AlekSIS Documentation", [author], 1)]
texinfo_documents = [
(
master_doc,
- "AlekSIS",
- "AlekSIS Documentation",
+ project,
+ f"{project} Documentation",
author,
- "AlekSIS",
+ project,
"One line description of project.",
"Miscellaneous",
),
diff --git a/docs/dev/00_index.rst b/docs/dev/00_index.rst
index 02a5cc03c73ee203e3c77c29866135c091fb3162..7a0783cf5ef4767c8bc78cca7c0cdf57f8a357ae 100644
--- a/docs/dev/00_index.rst
+++ b/docs/dev/00_index.rst
@@ -1,5 +1,5 @@
-Development
-===========
+Development of AlekSIS apps using the AlekSIS core
+==================================================
.. toctree::
:glob:
diff --git a/docs/dev/01_setup.rst b/docs/dev/01_setup.rst
index 24a64dbf7b7536193f7691538b2846409782519d..e52941af0c77b266ffd74bf410cccb0ef04b2678 100644
--- a/docs/dev/01_setup.rst
+++ b/docs/dev/01_setup.rst
@@ -109,13 +109,6 @@ development server against a local PostgreSQL database with password
ALEKSIS_maintenance__debug=true ALEKSIS_database__password=aleksis poetry run aleksis-admin runuwsgi
-.. figure:: /screenshots/index.png
- :scale: 50%
- :alt: Screenshot of index page
-
- After installing the development environment with default settings,
- you should see the index page with the Bootstrap style.
-
.. _Poetry: https://poetry.eustace.io/
.. _Poetry installation methods: https://poetry.eustace.io/docs/#installation
.. _Yarn: https://yarnpkg.com
diff --git a/docs/dev/03_run_tests.rst b/docs/dev/03_run_tests.rst
index ae38192ed8fb8fdaae51046839269cac1ef61af4..c50eda52d1c04d183c518a938a6f6a7a1c579ab3 100644
--- a/docs/dev/03_run_tests.rst
+++ b/docs/dev/03_run_tests.rst
@@ -6,8 +6,7 @@ Running default test suite
The test suite can be run using the `tox` tool::
- poetry run tox
-
+ tox
Enabling Selenium browser tests
-------------------------------
@@ -32,7 +31,7 @@ Selenium tests are enabled if `TEST_SELENIUM_BROWSERS` is non-empty.
To set variables, use env to wrap the tox ommand::
- poetry run env TEST_SELENIUM_BROWSERS=chrome,firefox tox
+ TEST_SELENIUM_BROWSERS=chrome,firefox tox
Using a Selenium hub on local Docker host
@@ -50,10 +49,9 @@ First, get Selenium Hub and one or more browser nodes up and running::
After that, you can run the test suite, setting the needed variables to use
Docker Hub::
- poetry run env \
- TEST_SELENIUM_BROWSERS=chrome,firefox \
- TEST_SELENIUM_HUB=http://127.0.0.1:4444/wd/hub \
- TEST_HOST=172.17.0.1 \
+ TEST_SELENIUM_BROWSERS=chrome,firefox \
+ TEST_SELENIUM_HUB=http://127.0.0.1:4444/wd/hub \
+ TEST_HOST=172.17.0.1 \
tox
The `TEST_HOST` variable is set to the Docker host's IP address, where the
diff --git a/docs/dev/04_materialize_templates.rst b/docs/dev/04_materialize_templates.rst
index 882604168d04ae6fd6085626305844a8648405e7..b997c32f293e6268a2deae5b69001abaf9a84e10 100644
--- a/docs/dev/04_materialize_templates.rst
+++ b/docs/dev/04_materialize_templates.rst
@@ -1,9 +1,9 @@
Materialize templates
======================
-AlekSIS frontend uses the `MaterializeCSS`_ framework and the `django-material`_ library.
+The AlekSIS frontend uses the `MaterializeCSS`_ framework and the `django-material`_ library.
-Internationalization
+Internationalisation
--------------------
Load the ``i18n`` template tag and start translating strings in templates with
diff --git a/docs/dev/06_merging_app_settings.rst b/docs/dev/06_merging_app_settings.rst
index 5c8bc1f65cced9153946bf36fbd005740e5fabb7..3e12ab95063e002326743afb733b360c094c7d9c 100644
--- a/docs/dev/06_merging_app_settings.rst
+++ b/docs/dev/06_merging_app_settings.rst
@@ -25,5 +25,5 @@ the following into your ``settings.py``::
}
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 does not exist in the
+settings to your ``settings.py``. Only settings that do not exist in the
main ``settings.py`` will be respected.
diff --git a/docs/dev/99_contributing.rst b/docs/dev/99_contributing.rst
deleted file mode 100644
index a5ffcc710e824f4cdcf235f12b25914efcf5ae28..0000000000000000000000000000000000000000
--- a/docs/dev/99_contributing.rst
+++ /dev/null
@@ -1,2 +0,0 @@
-.. include:: ../../CONTRIBUTING.rst
-.. include:: ../../CODE_OF_CONDUCT.rst
diff --git a/docs/index.rst b/docs/index.rst
index aded3b28d2e41186b0f871d0064627bc807a7a29..e91e043a3f5641137a256af27fc365fbb2ed3501 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -10,9 +10,12 @@ Welcome to AlekSIS-Core's documentation!
:maxdepth: 2
:caption: Contents:
+ preamble/00_index
+ user/00_index
admin/00_index
dev/00_index
ref/00_index
+ appendix/00_index
Indices and tables
diff --git a/docs/preamble/00_index.rst b/docs/preamble/00_index.rst
new file mode 100644
index 0000000000000000000000000000000000000000..02ffd34ae0ea254aefe7d361d8f28601e1794b7c
--- /dev/null
+++ b/docs/preamble/00_index.rst
@@ -0,0 +1,7 @@
+Introduction to AlekSIS and the AlekSIS core
+============================================
+
+.. toctree::
+ :glob:
+
+ *
diff --git a/docs/preamble/01_introduction.rst b/docs/preamble/01_introduction.rst
new file mode 100644
index 0000000000000000000000000000000000000000..0dcd9567b062189740dbf307d1b3459a0ac243d1
--- /dev/null
+++ b/docs/preamble/01_introduction.rst
@@ -0,0 +1,68 @@
+Introduction to AlekSIS
+=======================
+
+Welcome
+-------
+
+Welcome to AlekSIS, the Free School Information System! This handbook is
+a comprehensive guide on how to install, administer, and use AlekSIS and
+all included official apps. Its target audience are system
+administrators seeking to install and maintain an AlekSIS installation,
+people supporting the use of AlekSIS in daily processes in educational
+organisations, and end users who work with the software on a daily
+basis.
+
+On School Information Systems
+-----------------------------
+
+School Information Systems, or for short, SIS, are software suites that
+help educational organisations with managing personal information about
+all members (e.g. students, teachers, parents and guardians) as well as
+organisational data like plans, pedagogic track records, and much more.
+
+Generally, the goal of using School Information Systems is to help
+members of the school or other educational organisation to organise
+their work in learning and teaching, and to simplify digital processes,
+especially those that involve analytical evaluation, statistics, or
+information that is updated very frequently and should be made available
+to its recipients in a timely manner.
+
+Ideally, School Information Systems also promote transparency between
+teachers and students and improve sustainability by minimising the need
+for paperwork.
+
+AlekSIS, the Free School Information System
+-------------------------------------------
+
+School Information Systems have been on the rise ever since schools
+began digitising their management processes. Traditionally, the vendors
+of school management tools (like for timetabling, personal data
+management of teachers and students, etc.) also deliver wen applications
+that are tailored towards making the respective data available to those
+who need it.
+
+As most of these solutions are proprietary products, they tend to be
+limited to be used together with other software of their vendors, and do
+not integrate nicely with other software and with processes and data
+sets not in the focus of the developers.
+
+AlekSIS, in contrast, is a generic School Information System that aims
+at being universally usable for all processes and data sets in any
+educational organisation, and at interacting closely with other software
+components employed in management and lessons. You can find information
+on the possibilities for interacting with other software in the chapter
+[@sec:Integrations].
+
+The development and product team has set the following goals for
+AlekSIS, in their dedication to support learning and teaching in the
+digital world:
+
+- Create a high-quality software product, adhering to high standards
+ regarding data protection, data safety, security, and stability
+- Comply with as many national and regional data protection and school
+ laws as possible (cf. [@sec:Legal])
+- Provide an extensible framework, allowing schools or their supporting
+ IT companies to create their own apps (cf. [@sec:Development])
+- Help coding clubs and classes to understand the development as deeply
+ as necessary to use AlekSIS for learning and creating their own apps
+- Keep AlekSIS free, open, and transparent (cf. [@sec:FOSS])
diff --git a/docs/ref/00_index.rst b/docs/ref/00_index.rst
index 1f1524f16bf49c6a0f43cd0dcc4e135bebdd8413..9e452214d47658b936edbde780e69b1622a7bebe 100644
--- a/docs/ref/00_index.rst
+++ b/docs/ref/00_index.rst
@@ -1,5 +1,5 @@
-API and models reference
-========================
+Core API and models reference
+=============================
.. toctree::
:glob:
diff --git a/docs/user/00_index.rst b/docs/user/00_index.rst
new file mode 100644
index 0000000000000000000000000000000000000000..d8da67c26ad55de8d1dfb29a986bab355bde0803
--- /dev/null
+++ b/docs/user/00_index.rst
@@ -0,0 +1,7 @@
+Using basic features of the AlekSIS Core
+========================================
+
+.. toctree::
+ :glob:
+
+ *
diff --git a/docs/user/01_personal_account.rst b/docs/user/01_personal_account.rst
new file mode 100644
index 0000000000000000000000000000000000000000..da1c435fa7a77302343cf693cd40bf0886d04385
--- /dev/null
+++ b/docs/user/01_personal_account.rst
@@ -0,0 +1,92 @@
+Managing your personal account
+==============================
+
+Each logged in user has several options to provided through the AlekSIS
+core. Which of these items are display depends on whether the user has a
+person and what your system administrator has configured.
+
+.. _sec:Notifications:
+
+Notifications
+-------------
+
+The AlekSIS core has a built-in notification system which can be used by
+apps to send urgent information to specific persons (e. g. timetable
+changes). Notifications are shown on the dashboard and the notifications
+page reachable over the menu entry ``Notifications``. In addition to
+that, notifications can be sent to users through several communication
+channels. These channels can be switched on or off in your personal
+preferences (cf. [@sec:PersonalPreferences]).
+
+Setup two-factor authentication
+-------------------------------
+
+
+.. image:: ../_static/2fa.png
+ :width: 600
+ :alt: Configure two factor authentication
+
+AlekSIS provides two factor authentication using hardware tokens such as
+yubikeys which can generate OTPs or OTP application.
+
+To configure the second factor, visit `Account → 2FA` and follow the
+instructions.
+
+Please keep the backup codes somewhere safe so you do not lose access to
+your account. If you are unable to login with two factor authentication,
+please contact your site administrator.
+
+If you forget to safe your backup codes, but you are still logged in, visit
+`Account → 2FA`, and press `Show codes`.
+
+To disable two factor authentication, login to your account and navigate to
+`Account → 2FA`, then press the big red button to disable 2fa.
+
+Change password
+---------------
+
+If your system administrator has activated this function, you can change
+your password via ``Account → Change password``. If you forgot your
+password, there is a link ``Password forgotten?`` on this page which
+helps with resetting your password. The system then will send you a
+password reset link via email.
+
+Me page
+-------
+
+Reachable under ``Account → Me``, this page shows the personal
+information saved about you in the system. If activated, you can upload
+a picture of yourself or edit some information.
+
+.. _sec:PersonalPreferences:
+
+Personal preferences
+--------------------
+
+You can configure some behavior using the preferences under
+``Account → Preferences``. By default, the Core only provides some
+preferences, but apps can extend this list. You can find further
+information about such preferences in the chapter of the respective
+apps.
+
+- **Notifications**
+
+ - **Name format for addressing**: Here you can select how AlekSIS
+ should address you.
+ - **Channels to use for notifications:** This channel is used to
+ sent notifications to you (cf. [@sec:Notifications]).
+
+Third-party accounts
+--------------------
+
+If you logged in using a third-party account (e. g. a Google or
+Microsoft account), you can manage the connections to these accounts on
+the page ``Account → Third-party accounts``.
+
+Authorized applications
+-----------------------
+
+On the page ``Account → Authorized applications`` you can see all
+external applications you authorized to retreive data about you from
+AlekSIS. That can be services provided by your local institution like a
+chat platform, for example.
diff --git a/docs/user/20_pwa.rst b/docs/user/20_pwa.rst
new file mode 100644
index 0000000000000000000000000000000000000000..461bd113c14747843ac22f66a77bb22bde96d6d3
--- /dev/null
+++ b/docs/user/20_pwa.rst
@@ -0,0 +1,48 @@
+PWA (progressive web application)
+=================================
+
+What is a progressive web application?
+--------------------------------------
+
+A PWA is an application developed with common web technologies and
+delivered in form of a website, but which offers some features a
+traditional website does not and ,overall, creates an impression that
+resembles that of a native application.
+
+AlekSIS PWA features
+--------------------
+
+The AlekSIS PWA offers the following features (not all available on all
+platforms):
+
+- Installable and displayable in a separate window
+- Caching and serving, if given page cannot be accessed, of
+ non-interactive pages and needed assets
+- Provision of an offline fallback page if wanted page cannot be
+ accessed and there is no cached one
+- Indicator whether the served page is served from the PWA cache
+
+Installation of the PWA
+-----------------------
+
+The procedure to get a native feeling using the AlekSIS PWA varies from
+platform to platform. On some, you are prompted to add AlekSIS to your
+home screen of desktop using a popup; on others, you have to take action
+yourself and find the corresponding menu entry. As of the time of
+writing, “installable†PWAs are supported by all major platforms except
+Firefox Desktop which nevertheless supports the other features.
+
+- Chromium-based browsers (e.g. Chromium, Google Chrome, Microsoft
+ Edge) will usually prompt you to install the PWA by a popup on both
+ mobile and desktop devices; for the former using a banner and for the
+ latter using an appearing button in the adress bar. In both cases, a
+ click on the notification is enough to start the installation
+ process.
+- Firefox Mobile will also probably prompt you using a dot near the
+ menu button; then “install†has to been clicked.
+- On Safari you need to open the share popup and click on the “Add to
+ Home Screen†button.
+
+Independent of the used platform, AlekSIS can be accessed as an
+independent application entry, just like any other installed native
+application, after installation.