Update for RDMO 2.3.0

Author: jochenklar

docs/configuration/authentication/index.md

@@ -8,6 +8,8 @@ RDMO has three main modes for Authentication:
 
 If none of the modes is enabled, only a very basic login will be available and users need to be created using the Django Admin Interface.
 
+A custom middleware can be enabled to force users to aknowlege the [Terms of use](terms-of-use-middleware) of the instance.
+
 ---
 
 ```{toctree}
@@ -16,4 +18,5 @@ If none of the modes is enabled, only a very basic login will be available and u
 allauth
 ldap
 shibboleth
+terms-of-use-middleware
 ```

docs/configuration/authentication/terms-of-use-middleware.md

@@ -0,0 +1,23 @@
+# Terms of use middleware
+
+```{note}
+This feature was introduced in RDMO 2.3.
+```
+
+A custom middleware can be enabled to force users to aknowlege the Terms of Use (TOS) of the instance (which themselves are configured as [part of the theme](/themes/index.html#terms-of-use).
+
+To enable the middleware use the following in your `config/settings/local.py`:
+
+```python
+MIDDLEWARE.append('rdmo.accounts.middleware.TermsAndConditionsRedirectMiddleware')
+```
+
+If enabled, all users, regardless of the used authentication method, are redirected to the terms of use page when they first log in. Only if they accept, they are allowed to use the instance.
+
+If you update the terms of use, you can use, e.g.:
+
+```python
+ACCOUNT_TERMS_OF_USE_DATE = '2025-04-15'
+```
+
+to force all users which accepted the TOS before this date to accept them again.

docs/configuration/index.md

@@ -20,6 +20,7 @@ authentication/index
 export-formats
 cache
 logging
+openapi
 projects
 multisite
 ```

docs/configuration/openapi.md

@@ -0,0 +1,49 @@
+# OpenAPI, Swagger and Redoc
+
+```{note}
+This feature was introduced in RDMO 2.3.
+```
+
+Optionally, RDMO can be configured to use [drf-spectacular](https://drf-spectacular.readthedocs.io/en/latest/readme.html), which provides:
+
+* the automatic generation of an [OpenAPI 3.0 specification](https://www.openapis.org) at `/api/v1/schema/`
+* a browsable [Swagger](https://swagger.io) interface at `/api/v1/swagger/`
+* a browsable [Redoc](https://redocly.com) API documentation at `/api/v1/redoc/`
+
+To enable those features install the `openapi` dependency group together with RDMO:
+
+```bash
+pip install rdmo[openapi]
+```
+
+Then add the following to your `config/settings/local.py:
+
+```python
+INSTALLED_APPS += [
+    'drf_spectacular',
+    'drf_spectacular_sidecar'
+]
+
+REST_FRAMEWORK.update({
+    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
+    'DEFAULT_VERSIONING_CLASS': 'rest_framework.versioning.URLPathVersioning',
+    'DEFAULT_VERSION': 'v1',
+    'ALLOWED_VERSIONS': ('v1', ),
+})
+```
+
+and the following to your `config/urls.py`:
+
+```python
+urlpatterns = [
+    path('', home, name='home'),
+    path('about/', about, name='about'),
+    path('api/', api, name='api'),
+
+    path('', include('rdmo.core.urls')),
+    path('api/v1/', include('rdmo.core.urls.v1')),
+    path('api/v1/', include('rdmo.core.urls.v1.openapi')),  # <-- this line
+
+    path('admin/', admin.site.urls),
+]
+```

docs/configuration/projects.md

@@ -1,24 +1,31 @@
 # Project settings
 
-## Auto-Save
+## Project tasks and views
 
-By default, users need to save their input in the interview explicitly using the save button. This behavior can be changed adding the `PROJECT_QUESTIONS_AUTOSAVE` entry to your configuration.
+Before RDMO 1.6, tasks and views were completely hidden from the user, if no tasks or views have been configured. Now, interface elements are displayed regardless. If you don't need tasks and/or views in your RDMO instance, they can be hidden using:
 
 ```python
-PROJECT_QUESTIONS_AUTOSAVE = True
+PROJECT_ISSUES = False
+PROJECT_VIEWS = False
 ```
 
-With this setting, all input **except typing into text or text area fields** will be saved on the server immediately. This comprises, e.g. using the Navigation, radio buttons, check boxes.
+## Automatically synchronize tasks and views to projects
 
-## Project tasks and views
+```{note}
+This feature was introduced in RDMO 2.3.
+```
 
-Before RDMO 1.6, tasks and views were completely hidden from the user, if no tasks or views have been configured. Now, interface elements are displayed regardless. If you don't need tasks and/or views in your RDMO instance, they can be hidden using:
+Tasks and views can be configured to "belong" to specific catalogs. By default, this information is only used to filter the tasks and views for newly created projects. Afterwards, users can asign any task or view to any project.
+
+Optionally, RDMO can be configured to automatically update projects when the catalog for a task or view is changed. This can be done independently for tasks and views:
 
 ```python
-PROJECT_ISSUES = False
-PROJECT_VIEWS = False
+PROJECT_TASKS_SYNC = True
+PROJECT_VIEWS_SYNC = True
 ```
 
+If these settings are set, the user interface elements for changing the tasks or views in a project are hidden. 
+
 ## Sending tasks
 
 Sending tasks from projects is described [in the section on email](/configuration/email.md#send-tasks-via-email).
@@ -31,6 +38,18 @@ With RDMO 1.5, projects can be nested. If this feature is not desired, the UI el
 NESTED_PROJECTS = False
 ```
 
+## Visible projects
+
+In order to make projects available to all users (e.g. to be used as a template), project can be made visible
+by `site_managers` or Admins (see [Roles](/administration/users.md#roles)). This feature can be enabled using:
+
+```python
+PROJECT_VISIBILITY = True
+```
+
+Project visibility can be restricted to certain sites in a [Multisite Setup](/configuration/multisite.md) (i.e. when `MULTISITE = True`) or
+groups (when `GROUP = True`).
+
 ## Project file quota
 
 The size of files which can be uploaded for a project is limited (default: 10 MB). This can setting can be changed, e.g.:
@@ -57,3 +76,19 @@ PROJECT_CREATE_GROUPS = [
     'internal'
 ]
 ```
+
+## Project contact form
+
+```{note}
+This feature was introduced in RDMO 2.3.
+```
+
+Contact forms for each question in the interview can be used to allow the users to contact the management of the RDMO instance via email. To enable this feature use:
+
+```
+PROJECT_CONTACT = True
+PROJECT_CONTACT_RECIPIENTS = [
+    ('[email protected]', 'Manni Manager <[email protected]>'),
+    ...
+]
+```

docs/development/i18n.md

@@ -1,14 +1,39 @@
 Internationalisation
 ====================
 
-To update the locale files, change to the `rdmo` directory **inside** the `rdmo` repository and run:
+Run
+
+```bash
+rdmo-admin messages make
+```
+
+to create/update the `.po` files for the translation. Then run
+
+```bash
+rdmo-admin poedit de
+rdmo-admin poedit fr
+...
+rdmo-admin poedit de --js
+```
+
+to open the different `.po` files in [Poedit](https://poedit.net) and update the tranlations (manually).
+
+Afterwards run
+
+```bash
+rdmo-admin messages compile
+```
+
+to create/update the corresponding `.mo` files.
+
+Without `rdmo-admin` you need to change to the `rdmo` directory **inside** the `rdmo` repository and run:
 
 ```bash
 django-admin makemessages -a
 django-admin makemessages -a -d djangojs
 ```
 
-Then, edit the `.po` files in the `locale` directory. This can be done using [Poedit](https://poedit.net), e.g.
+To create the `.po` files. Then, edit the files using, e.g.:
 
 ```bash
 poedit locale/de/LC_MESSAGES/django.po
@@ -21,4 +46,4 @@ Afterwards run
 django-admin compilemessages
 ```
 
-to compile the `.po` file to a `.mo` file.
+to compile the `.po` file to `.mo` files.

docs/development/releases.md

@@ -1,25 +1,19 @@
 Releases
 ========
 
-0) Install [build](https://github.com/pypa/build) and [twine](https://github.com/pypa/twine): `python -m pip install build twine`
+0) Install `rdmo[dev]`.
 
 1) Ensure tests are passing.
 
-2) Update version in `rdmo/__init__.py`.
+3) Check that version in `rdmo/__init__.py`, `CHANGELOG.md` and *all the other things* are up to date.
 
-3) Build production front-end files
+4) Build production front-end files, source-distribution and wheel using:
 
+  ```python
+  rdmo-admin build
   ```
-  nvm use
-  npm install
-  npm run build:prod
-  ```
-
-4) Build source-distribution and wheel with `build`:
 
-  ```
-  python -m build
-  ```
+  which calls `npm ci` and `npm run build:prod` and `python -m build`
 
 5) Upload with `twine` to Test PyPI:
 
@@ -37,8 +31,4 @@ Releases
 
 8) Check https://pypi.org/project/rdmo/.
 
-9) Commit local changes.
-
-10) Push changes.
-
-11) Create release on [GitHub](https://github.com/rdmorganiser/rdmo/releases).
+9) Create release on [GitHub](https://github.com/rdmorganiser/rdmo/releases).

docs/development/setup.md

@@ -126,7 +126,6 @@ REST_FRAMEWORK['DEFAULT_RENDERER_CLASSES'] = (
 Then, initialize the application, using:
 
 ```bash
-python manage.py download_vendor_files  # download front-end vendor files
 python manage.py migrate                # initializes the database
 python manage.py setup_groups           # optional: create groups with different permissions
 ```
@@ -202,6 +201,14 @@ npm install    # to install the many, many javascript dependencies
 npm run watch  # to build the front-end and rebuild it when changing the source
 ```
 
+If you don't want to source the `nvm.sh` enviroment in every terminal session, you can use the shortcuts`rdmo-admin`:
+
+```bash
+rdmo-admin npm install
+rdmo-admin npm run watch
+...
+```
+
 Now the development server can be started (in a different terminal) using:
 
 ```

docs/installation/setup.md

@@ -29,6 +29,10 @@ python manage.py createsuperuser        # creates the admin user
 
 ## Third party vendor files
 
+```{warning}
+This step is only needed for older RDMO versions **before** RDMO 2.3.
+```
+
 By default third party vendor files (like jQuery or Bootstrap javascript's) are retrieved from the content delivery networks that they are hosted on. If you would like to avoid third party requests you could host them yourself. This can be achieved easily with two simple steps.
 
 1. download the vendor files from the cdns by running the provided script

docs/plugins/index.md

@@ -75,6 +75,22 @@ PROJECT_EXPORTS = [
 ]
 ```
 
+## Snapshot export plugins
+
+```{note}
+This feature was introduced in RDMO 2.3.
+```
+
+Custom snapshot exports are created very similar to project exports. They are inherited from `rdmo.projects.export.Export` as well, the difference is that `self.snapshot` is set, but `self.project` is not. For an example, please refer to `rdmo.projects.exports.RDMOXMLExport`.
+
+The export plugin needs to be added to the `PROJECT_SNAPSHOT_EXPORTS` in `config/settings/local.py`, e.g.:
+
+```python
+PROJECT_EXPORTS = [
+    ('xml', _('as RDMO XML'), 'rdmo.projects.exports.RDMOXMLExport'),
+]
+```
+
 ## Project import plugins
 
 Similarly, custom project imports can be created implementing a class inheriting from `rdmo.projects.imports.Import`. They can be used to import project data from files which are uploaded by the user.